第 28 课：AI 能力边界与项目知识库搭建

第六章：Claude Code 工程化工作流 | 第 28 课

课前思考

你打开 Claude Code，想让它帮你加一个功能。你是不是经常这样开头：「帮我加个用户评论功能」？

然后它写了一堆代码，你跑起来发现——变量命名风格和项目完全不一样，数据表设计跟你现有的用户系统对不上，甚至用了你们团队根本不用的框架。

问题出在哪？不是 AI 不够聪明，是你没有给它看「说明书」。

一、AI 的能力边界

AI 擅长什么

把 Claude Code 想象成一个极其聪明但需要明确指令的高级工程师：

几秒钟内读完几千行代码，找到你需要的部分
根据描述快速生成代码框架和样板
发现明显的语法错误、常见安全漏洞、性能反模式
批量执行重复性工作：重命名变量、格式化代码、生成文档注释
按给定规范进行代码审查，比人更耐心和全面

有明确规则、可以自动化的工作，AI 都能做得很好。

AI 不擅长什么

理解业务逻辑：除非你详细告诉它，否则它不知道你们公司的订单流程
技术选型和架构决策：需要权衡利弊的决策，需要你的经验
团队的隐性规范：「所有 API 都要加日志」「错误码必须用枚举」——AI 不会主动知道
判断「真正完成」：AI 可能觉得「看起来差不多了」就停下来，而不是基于客观标准

正确的协作姿势

你的职责：想清楚做什么 → 做决策 → 把关质量 → 验证结果
AI 的职责：理解上下文 → 执行编码 → 查找信息 → 发现问题

核心原则：你是指挥官，AI 是执行者。你负责方向和判断，AI 负责速度和广度。

二、CLAUDE.md：项目的使用说明书

Claude Code 启动时，会自动读取项目根目录的 CLAUDE.md（也支持 AGENTS.md）。这就是你的项目的「使用说明书」。

一个高质量的 CLAUDE.md 至少包含以下内容：

markdown

# 项目概述
在线教育平台，提供课程管理、用户学习、作业提交等功能。

# 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express + PostgreSQL

# 项目结构
src/
├── components/     # React 组件（PascalCase）
├── pages/         # 页面组件
├── api/           # API 调用层
├── utils/         # 工具函数（camelCase）
└── types/         # TypeScript 类型定义

# 代码规范
- 禁止使用 any 类型
- 所有 API 调用必须有错误处理
- 数据库操作使用参数化查询
- 敏感信息（密码、token）不能出现在日志中

# 开发流程
1. 从 main 分支创建功能分支
2. 每完成一个独立功能立即 git commit
3. 开发完成后提交 PR，等待审查

# 注意事项
- 不要提交 node_modules/、dist/、.env 文件
- 环境变量通过 .env.example 同步，不提交真实值

黄金法则：如果你发现自己重复两次同样的指令，就把它写进 CLAUDE.md。

三、分层规范体系

对于更大的项目，一个 CLAUDE.md 不够。使用 .claude/rules/ 目录建立分层规范：

.claude/
├── rules/
│   ├── 01-coding-standards.md   # 编码规范
│   ├── 02-api-design.md         # API 设计规范
│   ├── 03-testing.md            # 测试规范
│   ├── 04-git-workflow.md       # Git 工作流
│   └── 05-security.md           # 安全规范

Claude Code 会自动读取 .claude/rules/ 下的所有文件，作为项目级的「宪法」。

四、技术决策记录（ADR）

当项目变复杂，AI 需要理解「为什么当初这样设计」。在 docs/decisions/ 目录下维护 ADR：

markdown

# ADR-001: 选择 PostgreSQL 作为数据库

## 状态
已采纳

## 决策
选择 PostgreSQL

## 理由
1. 更好的 JSON 支持，适合存储课程内容
2. 更强大的全文搜索功能
3. 团队成员更熟悉

有了 ADR，当你三个月后让 AI 重构数据库层时，它会自动参考这些历史决策，而不会建议你「换成 MongoDB 试试」。

五、Token 经济学入门

作为 PM，你不需要精通 API 计费模型。但你需要理解一个核心原则：

上下文越大，花费越高。

优化策略：

指定文件路径比模糊描述更好（「改 src/api/user.ts」优于「改一下用户相关代码」）
指明功能范围比笼统说「项目有问题」更聚焦
删除客套话，直接说任务
使用 CLAUDE.md 和 .claude/rules/ 减少重复指令

课后练习

给你最近在做的项目写一份 CLAUDE.md，至少包含项目概述、技术栈、项目结构、代码规范四个部分
用 Claude Code 打开这个项目，看它是否能根据 CLAUDE.md 理解你的项目结构
思考：你的团队有哪些隐性规范还没有文档化？列出至少 3 条

第 28 课：AI 能力边界与项目知识库搭建 ​

课前思考 ​

一、AI 的能力边界 ​

AI 擅长什么 ​

AI 不擅长什么 ​

正确的协作姿势 ​

二、CLAUDE.md：项目的使用说明书 ​

三、分层规范体系 ​

四、技术决策记录（ADR） ​

五、Token 经济学入门 ​

课后练习 ​

课程讨论