课程目录

第 5 课 · AI 原生软件开发生命周期

Build: Plan and Context

本篇听书

5 分钟 · 双主持人讲解

配套视频里没有与本篇对应的段落

Build：先计划，再让上下文服务实现

在 AI 原生构建中，第一份工程产物不是代码，而是可审查的 plan.md。工程师让 Claude 在计划模式中读取代码库、意图和规范，反复追问风险、替代方案与验证方法；计划获接受后才实现。与此同时，CLAUDE.md 提供团队稳定上下文，让每次会话少走相同弯路。

学习目标

  • 能写出另一位工程师可独立执行的实现计划。
  • 能用短小、版本化的 CLAUDE.md 提供项目上下文。
  • 能区分计划、项目记忆、Skill 与 Hook 的职责。

核心概念

Claude 官方文档说明，计划模式允许读取文件并提出方案，但在批准前不编辑源文件。这把设计审查放到修改成本较低的时刻。计划应说明会改哪些文件、以什么顺序、有哪些风险、用什么测试证明，并在实际实现偏离时与代码同一提交更新。

CLAUDE.md 则像新成员第一天需要的说明：构建/测试/检查命令、关键约定、架构边界以及代理经常犯的具体错误。它不是百科全书；过期或冗长内容会消耗上下文并稀释真正重要的指令。团队应把它纳入代码评审，通过 Git 记录修订，并给变更指定代码所有者。

四种工件可以这样分工：当前变更的路线在 plan.md；项目的稳定事实在 CLAUDE.md；按任务触发的专业流程在 Skill；必须执行的限制在 Hook/CI。现有 Jira 或 ServiceNow 等系统不必被强行替换，但必须指定权威源，至少让工单 ID 和提交 SHA 相互可追踪。

实践步骤

  1. 在计划模式中提供已接受的意图和规范，要求 Claude先探索而不修改。
  2. 追问“最可能破坏什么、风险最高的步骤是什么、有哪些未采用的方案”。
  3. 把计划细化到文件、依赖顺序、回退方式和可执行测试；让未参与对话的工程师试读。
  4. 接受计划后再实现；偏离计划时同步修改 plan.md，不要让审计记录变成过期故事。
  5. 定期精简 CLAUDE.md：删除可从代码直接推断的内容、失效命令与一次性背景。

以下两个文件均为 AIKnow 自行创作的 illustrative templates（示意模板），不是 Anthropic 原文，也不是可直接复制到所有项目的配置。

plan.md 示意模板：

# Plan: FIN-042 报销单据缺失提醒

依据：spec/FIN-042.md @ 4c98d11

## 变更文件与顺序
1. receipt_rules/schema.json：定义规则 ID 与严重度枚举；先更新契约测试。
2. expense_api/receipt_check.py：实现只读校验与 800ms 降级。
3. web/ExpenseSubmit.tsx：展示可聚焦的缺失摘要。
4. tests/：补充权限、超时、日志脱敏和前端无障碍测试。

## 主要风险
- Web 与 API 枚举版本不一致；由契约测试阻断。
- 降级路径被误当成功；界面必须显示“待财务复核”。

## 验证与回退
运行 make test-contract、make test-expense、make a11y。
功能由 receipt_precheck 开关控制；回退只关闭开关，不删除审计数据。

CLAUDE.md 示意模板：

# 费用平台协作上下文

## 必跑命令
- 单元测试：make test
- 契约测试：make test-contract（需要本地容器）
- 静态检查：make lint

## 架构边界
- web/ 不直接读取单据对象存储；只通过 expense_api/ 获取脱敏结果。
- rules/ 是规则权威源，前端不得复制判断逻辑。

## 易错事项
- 金额统一使用 Decimal；禁止二进制浮点。
- generated/ 由脚本生成，不手工修改。
- 修复缺陷时先复现为失败测试，未经批准不改测试期望。

常见误区

  • 计划只列任务名。 没有顺序、风险和证明方法的清单，无法提前暴露设计问题。
  • 计划批准后永不更新。 实现偏离而工件不变，会破坏评审和追溯。
  • 把整份架构文档复制进 CLAUDE.md。 应保留高频、稳定、可行动的上下文，并链接详细资料。
  • 把自动接受当成熟度。 只有测试、权限、沙箱和评审门稳定后，例行工作的自主范围才适合扩大。

动手练习

选择一个预计修改三到五个文件的小变更，使用上面的格式写计划。请同事只读计划，指出缺失的依赖与验证。然后把当前仓库的 CLAUDE.md（或新草稿）压缩为一页：每一条都要回答“若代理不知道，会造成什么可观察错误？”无法回答的内容移出主文件。

要点回顾

计划模式把工程判断前移，plan.md 让实现路径可审查，CLAUDE.md 让稳定团队知识进入每次会话。二者都必须短、可行动、版本化，并与测试和评审证据连接。更高自主性是可靠约束的结果，不是绕过计划的捷径。

参考来源