AI Coding 最佳实践 —— 从上下文工程到 Spec 驱动开发

AI Coding 的核心等式

AI 输出质量
=
上下文质量 × 任务清晰度 × 模型能力

模型能力你控制不了。
但 上下文质量 和 任务清晰度 完全由你控制。

AI Coding 的三个层次

Level 1: 问答式
          "帮我写一个排序函数"

          → AI 生成，粘贴到项目

          → 风格不一致，需要大量修改
        
无上下文
Level 2: 上下文感知
          有 CLAUDE.md + 打开相关文件

          → AI 了解项目规范

          → 生成符合风格的代码
        
被动适应
Level 3: Spec 驱动
          PRD → Arch → Tasks

          → AI 在清晰规约下工作

          → 方向正确、质量可控、可追溯
        
主动设计

关键洞察
AI Coding 的瓶颈从来不是模型不够聪明，而是你给它的上下文不够好。

CLAUDE.md = 项目的 AI 入口文件

Claude Code 每次会话自动加载。它定义了 AI 在这个项目中的"行为准则"。

✅ 好的 CLAUDE.md

## 规则
- 所有函数必须有类型提示
- API 端点必须做输入校验
- 不引入超过 3 个新依赖

## 禁忌
- 不要在 API 层直接操作数据库
- 不要硬编码敏感信息
- 不要跳过测试直接提交

每条都可执行、可验证

❌ 差的 CLAUDE.md

## 规则
- 代码要写好
- 注意安全
- 使用合适的设计模式

全是空话，AI 没有可执行的约束

CLAUDE.md 设计五原则

原则	说明	例子
具体而非抽象	可验证的规则，而非模糊描述	"函数不超过 20 行" 而非 "代码要干净"
约束而非建议	"必须" 而非 "建议"	"所有函数必须有类型提示"
说做什么也说不做什么	禁忌往往比规则更重要	"不要在 API 层操作数据库"
保持更新	发现新规则立即更新	踩坑后用 CLAUDE.md 防止再犯
短小精悍	每行一条规则，控制在 100 行内	别写散文

AGENTS.md = 跨平台 Agent 指令

如果同时使用多个 AI 编程工具（Claude Code、Codex、Copilot、Cursor），AGENTS.md 是它们共同的"通用规范"。CLAUDE.md 则是 Claude Code 的专属补充配置。

AGENTS.md 放什么

项目定位和背景
通用编码规范（跨工具适用）
架构约定（分层、模块边界）
工作约定（提交格式、分支策略）
安全要求（不硬编码密钥等）

CLAUDE.md 放什么

Skills 引用和配置
Hooks 触发规则
Memory 文件路径
Claude Code 特有的工作流
项目特有的 MCP Server 配置

协同策略

只用 Claude Code
CLAUDE.md 就够了

        多工具协作

        AGENTS.md（通用规则）

        + CLAUDE.md（Claude Code 专属）

AGENTS.md 模板示例

# AGENTS.md — 跨平台 AI Agent 指令

## 项目背景
AI 学习工作坊，11 个渐进式模块

## 通用编码规范
- 语言: Python 3.10+
- 每个模块必须配 README + Demo + 教学指南
- 代码注释用中文，标识符用英文

## 架构约定
- 模块命名: 0XX-topic-learning/
- 不跨模块引用代码

## 工作约定
- Commit: type: 中文描述
- 新建模块后更新 docs/learning-log.md

CLAUDE.md vs AGENTS.md 总结
AGENTS.md → 跨平台通用规则（Claude Code、Codex、Cursor 等）
CLAUDE.md → Claude Code 专属配置（Skills、Hooks、Memory 路径）
只用 Claude Code → 只需 CLAUDE.md | 多工具 → AGENTS.md + CLAUDE.md

Memory 解决"会话失忆"问题

没有 Memory
会话 1: 决定用 Redis
会话 2: 不知道，推荐 Memcached

→

        有 Memory

        会话 1: 决定用 Redis → 写入 memory/

        会话 2: 加载 memory/ → 知道用 Redis

五种 Memory 类型

类型	文件	记录什么
user	user_role.md	用户角色、目标、技术背景、偏好
project	project_context.md	为什么做这个项目、核心约束、干系人
project	decisions.md	技术选型及理由（为什么选 Redis 不选 Memcached）
project	architecture_decisions.md	架构层面的关键决策（分层策略、API 设计风格）
feedback	feedback.md	用户对 AI 协作方式的偏好和反馈

Memory 黄金法则
记录 WHY 而非 WHAT。WHAT 在代码里，WHY 在 Memory 里。
"我们选 Redis 而不是 Memcached，因为需要持久化和复杂数据结构" ← 这无法从代码推导。

Skill = 可复用的 AI 能力模板

Skill 是预定义的 Checklist，告诉 AI "当遇到这类任务时，按这个步骤做"。

没有 Skill

用户: "review 我的代码"
AI: "看起来不错"（泛泛而谈）

有 Skill

用户: "review 我的代码"
AI: 加载 code-review Skill
  → 1. 安全审查
  → 2. 逻辑审查
  → 3. 性能审查
  → 4. 风格审查
  → 5. 结构化报告

Hooks = 事件驱动的自动化

事件	触发时机	典型用途
`PostToolUse`	Write/Edit 文件后	自动 ruff/black 格式化
`PreToolUse`	Bash 命令执行前	检测危险命令（rm -rf, push --force）
`SessionStart`	会话开始时	加载 Memory、记录日志
`PreCompaction`	上下文压缩前	自动将关键信息写入 Memory

上下文窗口是 AI 的"工作记忆"

你放进来的东西决定了 AI 的输出质量。Context Engineering = 主动设计 AI 看到什么。

上下文分层

系统层 — 模型能力、工具集 — 始终加载

项目层 — CLAUDE.md、AGENTS.md — 会话开始时

记忆层 — MEMORY.md、决策记录 — 会话开始时

任务层 — Spec 文档、Task 文件 — 任务切换时

即时层 — 打开的文件、当前对话 — 实时

✅ 好的上下文

只打开当前任务相关的 2-3 个文件
CLAUDE.md 控制在 100 行以内
Memory 定期清理过期记录
一个 Task 一个 Task 地推进

❌ 上下文污染

打开 15 个无关文件
CLAUDE.md 写了 500 行
Memory 记录过期信息（项目已迁移但 Memory 未更新）
一次给 AI 太多任务

Spec Driven Development

PRD
要做什么

→

Architecture
怎么做

→

Tasks
分步实现

→

Coding
逐 Task 实现

每个阶段评审通过后才进入下一阶段。在写代码之前，把方向想清楚。

不用 Spec

需求 → AI 写代码 → 审查
  → 方向偏了 → 重写
  → 又偏了 → 再重写
  → 质量不可追溯

用 Spec

需求 → PRD（确认）
  → Arch（确认）
  → Tasks（确认）
  → 逐 Task 实现
  → 对照验收标准验证
  → 方向正确、可追溯

Spec 的三个层次

文档	回答的问题	产出
01-prd.md	用户要什么？验收标准是什么？	用户故事、功能列表（P0/P1/P2）、验收条件
02-architecture.md	用什么技术？模块怎么划分？	技术选型、数据模型、API 契约、代码结构
03-tasks.md	分几步？依赖关系？	Task 列表（30min-2h/个）、依赖关系图、AI Prompt

Spec 的关键检验
"如果 Spec 写好了，换一个人（或另一个 AI 会话）能独立完成吗？"
如果答案是"不能" → Spec 不够清晰。

AI 开发全流程

PRD

→

Arch

→

Tasks

→

Coding

→

Review

→

Test

→

Deploy

→

Retro

各阶段详解

PRD — 产品需求文档
把模糊需求变成结构化功能描述。每个功能配验收标准。

Architecture — 架构设计
技术选型 + 组件图 + 数据模型 + API 契约。人决策，AI 出方案。

Tasks — 任务拆解
拆成 30min-2h 的独立 Task，明确依赖关系和验收条件。

Coding — 逐 Task 实现
一次只做一个 Task。打开相关文件 + Task 描述 → AI 实现 → 验证 → 提交。

Review — 三层审查
AI 快速扫 → 人检查设计 → 测试自动验证。对照 PRD 和 Arch 检查。

Test — 多层测试
单元 → 集成 → API → 验收。AI 根据 Task 自动生成测试用例。

Deploy — 部署上线
按检查清单逐项确认：测试通过、配置就绪、监控告警、回滚方案。

Retro — 回顾优化
更新 Memory 记录经验，更新 CLAUDE.md 加新规则，创建可复用的 Skill。

十大反模式

#	反模式	后果	正确做法
1	没写 CLAUDE.md 就开始	AI 不了解规范	先写好 CLAUDE.md
2	跳过 PRD 直接写代码	方向容易偏	PRD → Arch → Tasks
3	一次给太多任务	输出质量断崖下降	一次一个 Task
4	打开不相关的文件	上下文污染	只开当前任务需要的
5	不用 Memory	下次会话重复讨论	决策后立即写入
6	Review 只看代码不看逻辑	漏掉设计问题	对照 PRD/Arch 审查
7	不写验收标准	不知道何时完成	PRD 就写好
8	忽视测试	回归 Bug 频发	实现后立即生成测试
9	过度依赖 AI	不理解的代码也合入	每行代码都要理解
10	CLAUDE.md 从不更新	规则过时，AI 退化	每次踩坑后更新

一句话总结
AI Coding 的质量，80% 取决于你给它设计的工作环境，20% 取决于你的 Prompt。模型反而是最小的变量。