关于 AI 驱动开发（AIDD）实践

摘要

随着 AI 编码助手（如 Claude Code、Cursor、Copilot、Kiro 等）的快速发展，软件开发正在经历一场范式转变。本文基于 Web Nexus 项目的实践经验，系统性地总结了 AI 驱动开发（AI-Driven Development, AIDD）的最佳实践，涵盖项目配置架构、文档组织策略、Agent 系统设计、工具链集成等核心领域，为企业级项目的 AIDD 实践提供参考框架。

核心理念

AIDD 的本质

AI 驱动开发不是简单地使用 AI 工具写代码，而是构建一个可持续、可扩展、可审计的 AI 辅助开发生态系统。

AI 驱动开发（AI-Driven Development, AIDD） 是一种将 AI 工具深度集成到软件开发全生命周期的方法论。与传统的"AI 辅助编码"不同，AIDD 强调：

• 系统化集成：AI 不是可选工具，而是开发流程的核心组成部分
• 上下文感知：AI 理解项目架构、编码规范、业务逻辑
• 自动化决策：AI 参与架构设计、代码审查、测试生成等高级任务
• 持续学习：项目知识通过文档和记忆系统不断积累

三大支柱：

1. 约束驱动（Constraint-Driven）

   • 通过明确的规则和约束引导 AI 行为
   • 将隐性知识显性化为可执行的规则
   • 用约束替代重复的人工审查

2. 上下文优先（Context-First）

   • 为 AI 提供充分的项目上下文
   • 分层组织项目知识（架构、规范、模式）
   • 动态加载相关文档和示例

3. 人机协作（Human-AI Collaboration）

   • AI 执行重复性和机械性任务
   • 人类负责决策和创造性工作
   • 建立清晰的责任边界

核心价值主张

对开发者：

• ⚡ 减少 70% 的样板代码编写时间
• 🎯 专注于业务逻辑而非语法细节
• 📚 自动遵循项目规范和最佳实践
• 🔍 实时获取最新技术文档

对团队：

• 📖 知识沉淀为可执行的指导文件
• 🔄 新成员快速上手项目规范
• ✅ 自动化质量检查减少人工审查
• 🚀 加速功能交付周期

对项目：

• 🏗️ 一致的代码风格和架构模式
• 🛡️ 强制执行安全和性能规范
• 📊 可追溯的开发决策历史
• 🔧 易于维护和演进的代码库

架构体系

AIDD 架构采用分层设计，每一层都有明确的职责和接口。

┌─────────────────────────────────────────────────────────┐
│  Layer 1: 项目记忆层（Project Memory）                   │
├─────────────────────────────────────────────────────────┤
│  CLAUDE.md + AGENTS.md + docs/ + .claude/               │
│  职责：定义项目规范、架构模式、开发约束                    │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────┴────────────────────────────────┐
│  Layer 2: 专用 Agent 层（Specialized Agents）            │
├─────────────────────────────────────────────────────────┤
│  web-nexus-dev + code-reviewer + tester                 │
│  职责：专业领域的 AI 助手，具备深度技术栈知识              │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────┴────────────────────────────────┐
│  Layer 3: Skills/Commands 层（Skills Layer）             │
├─────────────────────────────────────────────────────────┤
│  Speckit Workflow + Custom Commands                     │
│  职责：可复用的工作流和命令，串联开发生命周期               │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────┴────────────────────────────────┐
│  Layer 4: MCP 工具服务器层（MCP Servers）                 │
├─────────────────────────────────────────────────────────┤
│  职责：外部知识源集成，提供实时文档和工具                   │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────┴────────────────────────────────┐
│  Layer 5: 工作流与钩子层（Workflows & Hooks）             │
├─────────────────────────────────────────────────────────┤
│  PostToolUse + PreCommit + Custom Hooks                 │
│  职责：自动化触发质量检查和格式化                          │
└─────────────────────────────────────────────────────────┘

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

# Individual Preferences
- @~/.claude/my-project-instructions.md

This code span will not be treated as an import: `@anthropic-ai/claude-code`

> /init

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

paths: src/api/**/*.ts

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

paths: src/**/*.{ts,tsx}

# TypeScript/React Rules

paths: {src,lib}/**/*.ts, tests/**/*.test.ts

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared

# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

问题:
  通用 AI Agent 在处理复杂任务时的局限性：
  - 缺乏领域专业知识
  - 工具选择不够精准
  - 上下文理解不够深入

解决方案:
  为不同开发场景创建专用 Agent：
  - 后端架构 → service-copilot
  - 前端开发 → nexthub-dev
  - 日常开发 → 通用 Agent

添加新端点工作流:
  1. 阅读相关文件了解现有实现
  2. 确认修改不会破坏现有功能
  3. 实施代码变更
  4. 添加单元测试和集成测试
  5. 运行 make lint, make typecheck, make test
  6. 手动验证功能
  7. 提交代码（使用 /commit）

数据库迁移工作流:
  1. 修改 SQLAlchemy 模型
  2. 生成迁移: make migrate-create
  3. 审查迁移文件
  4. 应用迁移: make migrate
  5. 验证数据库状态
  6. 更新相关测试

全栈功能开发工作流:
  1. @service-copilot 规划后端 API
  2. 实施后端端点和测试
  3. @nexthub-dev 创建前端页面
  4. 集成 Admin API
  5. 浏览器自动化测试验证
  6. /review-pr 代码审查

利用 Claude Code Plugin 快速初始化

插件让你能够使用可在项目和团队中共享的自定义功能来扩展 Claude Code。

Claude Code Plugin Docs

插件可以包含：自定义代理、Skills/Command、钩子、MCP 服务器和 LSP 服务器。

常见错误：不要将 commands/、agents/、skills/ 或 hooks/ 放在 .claude-plugin/ 目录内。只有 plugin.json 应该在 .claude-plugin/ 内。所有其他目录必须位于插件根级别。

有关所有插件组件的完整技术规范，请参阅插件参考。

Claude Code 官方插件仓库

实践模式

文档驱动开发（Documentation-Driven Development）

核心理念: 文档是项目的"单一真相来源"（Single Source of Truth）

传统方式:
  代码 → 文档（经常过时）
  问题: 文档滞后，AI 无法获取最新信息

AIDD 方式:
  文档 ↔ 代码（同步更新）
  优势: AI 始终理解最新架构和规范

实施步骤:

1. 建立文档结构:
   CLAUDE.md (主导航)
   .claude/rules/ (详细规则)
   docs/ (架构文档、PRD)

2. 定义硬性规则:
   - 第三方库版本管理
   - 架构约束
   - 安全要求

3. 编写代码示例:
   - 每个规则配代码示例
   - 展示正确和错误的做法

4. 持续更新:
   - 架构变更 → 立即更新文档
   - 新功能 → 添加到文档
   - 重构 → 更新相关章节

示例：添加新功能的文档流程:

场景: 添加 Rate Limit Cooldown 功能

步骤 1: 更新架构文档
  文件: .claude/rules/rate-limit-cooldown.md
  内容:
    - 功能概述
    - 配置方法
    - API 端点
    - 故障排查

步骤 2: 更新主导航
  文件: CLAUDE.md
  添加: "详细的 Rate Limit Cooldown 实现见 .claude/rules/rate-limit-cooldown.md"

步骤 3: 实施代码
  AI 参考文档实施功能

步骤 4: 验证一致性
  代码实现 ↔ 文档描述
  确保完全一致

上下文效率优化

问题: AI 上下文窗口有限，如何最大化利用？

解决方案: 模块化 + 按需加载

优化前:
  单一 AGENTS.md: 2384 行
  问题: 加载慢，信息密度低

优化后:
  AGENTS.md: 392 行（导航）
  .claude/rules/: 12 个专题文件
  效果: 90% 上下文效率提升

模块化原则:

1. 单一职责:
   每个文件只关注一个主题

2. 合理粒度:
   100-700 行为宜

3. 清晰索引:
   主文件提供导航

4. 交叉引用:
   相关文件互相链接

Agent 协作模式

模式 1: 规划-实施分离

流程:
  @service-copilot 规划
  → Handoff: Start Implementation
  → 通用 Agent 实施

优势:
  - 规划阶段深度分析
  - 实施阶段专注执行
  - 职责清晰，效率高

模式 2: 前后端协作

流程:
  @nexthub-dev 发现需要新 API
  → Handoff: Backend Integration
  → @service-copilot 设计 API
  → 通用 Agent 实施后端
  → @nexthub-dev 集成前端

优势:
  - 前后端需求对齐
  - API 设计符合前端需求
  - 减少返工

模式 3: 测试驱动协作

流程:
  /tdd 生成测试
  → 通用 Agent 实施代码
  → /review-pr 代码审查
  → /e2e 端到端验证

优势:
  - 质量保证
  - 自动化验证
  - 持续改进

安全优先原则

核心理念: 安全检查自动化，主动防御而非被动修复

实施策略:
  1. 代码生成时:
     - AI 自动应用安全最佳实践
     - 避免 OWASP Top 10 漏洞

  2. 代码审查时:
     - /security-review 自动触发
     - 检测注入攻击、XSS、CSRF

  3. 部署前:
     - 运行安全扫描
     - 验证依赖库无已知漏洞

示例规则:
  - 所有 admin 端点必须有 require_admin
  - 所有用户输入必须验证和清理
  - 敏感数据必须加密存储
  - API Key 必须哈希存储

性能与效率优化

上下文窗口优化

问题: AI 上下文窗口有限（200K tokens），如何高效利用？

优化策略:

1. 模块化文档:
   优化前: 单一文件 2384 行
   优化后: 12 个模块文件
   效果: 90% 上下文效率提升

2. 按需加载:
   - Claude Code 自动加载 .claude/rules/
   - 只加载相关模块
   - 避免加载无关信息

3. 文档压缩:
   - 使用代码示例代替长篇描述
   - 使用 YAML 格式代替自然语言
   - 删除冗余信息

4. 交叉引用:
   - 主文件提供导航
   - 详细内容在专题文件
   - 避免重复内容

实测数据:

优化前:
  CLAUDE.md: 37 KB
  AGENTS.md: 58 KB
  总计: 95 KB
  上下文利用率: 40%

优化后:
  CLAUDE.md: 37 KB（更新）
  AGENTS.md: 10 KB（优化）
  .claude/rules/: 12 个文件
  总计: ~60 KB（有效内容）
  上下文利用率: 85%

效率提升技巧:

1. 使用 Skills 快捷方式:
   - /commit 代替手动 git 操作
   - /review-pr 代替手动代码审查
   - /tdd 强制测试驱动开发

2. 使用专用 Agent:
   - 后端任务 → @service-copilot
   - 前端任务 → @nexthub-dev
   - 避免使用通用 Agent 处理复杂任务

3. 利用 Handoffs:
   - 规划 → 实施 → 测试
   - 自动切换 Agent
   - 减少上下文切换

4. 自动化工作流:
   - pre-commit hook 自动 lint
   - post-tool-call hook 自动测试
   - 减少手动操作

常见陷阱与解决方案

文档陷阱

陷阱 1: 文档过时

问题: 代码更新了，文档没更新，AI 使用过时信息

症状:

- AI 生成的代码不符合当前架构
- AI 引用已删除的文件或函数
- AI 使用已废弃的 API

解决方案:

1. 建立文档更新流程:
   代码变更 → 立即更新文档
   重构 → 更新相关章节
   新功能 → 添加到文档

2. 使用 /doc-updater skill:
   自动更新 codemaps 和文档
   生成 docs/CODEMAPS/*
   更新 README

3. 代码审查检查:
   PR 必须包含文档更新
   检查文档与代码一致性

陷阱 2: 文档过于冗长

问题: 文档太长，AI 上下文窗口利用率低

症状:

- AI 响应慢
- AI 遗漏重要信息
- 上下文溢出

解决方案:

1. 模块化拆分:
   单一文件 → 多个专题文件
   每个文件 100-700 行

2. 使用代码示例:
   长篇描述 → 简洁代码示例
   自然语言 → YAML 格式

3. 删除冗余:
   重复内容 → 交叉引用
   过时信息 → 删除

Agent 使用陷阱

陷阱 3: 使用错误的 Agent

问题: 用通用 Agent 处理复杂任务，效率低下

症状:

- Agent 响应慢
- 生成的代码不符合最佳实践
- 缺乏领域专业知识

解决方案:

决策树:
  后端架构/数据库/性能 → @service-copilot
  Next.js/前端/浏览器 → @nexthub-dev
  简单代码修改 → 通用 Agent

示例:
  ✗ 错误: 用通用 Agent 设计数据库架构
  ✓ 正确: 用 @service-copilot 设计数据库架构

  ✗ 错误: 用 @service-copilot 调试 hydration 错误
  ✓ 正确: 用 @nexthub-dev 调试 hydration 错误

陷阱 4: 忽略 Handoffs

问题: 不使用 Handoffs，手动切换 Agent，效率低

症状:

- 需要重新描述上下文
- Agent 之间信息丢失
- 工作流不连贯

我需要继续添加第7章的内容，但要注意分段输出。让我继续添加解决方案和更多陷阱。

解决方案:

使用 Handoffs:
  规划完成 → 点击 "Start Implementation"
  前端需要后端 → 点击 "Backend Integration"
  需要测试 → 点击 "Test in Browser"

优势:
  - 自动预填充提示
  - 保留上下文
  - 工作流连贯

MCP 工具陷阱

陷阱 5: 不使用 Context7 MCP

问题: 依赖训练数据中的旧知识，使用过时 API

症状:

- 生成的代码使用已废弃的 API
- 参数签名不匹配
- 导入路径错误

解决方案:

文档优先原则:
  1. 总是先查询 Context7 MCP
  2. 验证 API 签名和参数
  3. 使用最新文档生成代码

示例:
  ✗ 错误: 直接生成 Starlette 代码
  ✓ 正确: 先查询 Context7 MCP，再生成代码

  # 正确流程
  1. resolve-library-id(libraryName="Starlette")
  2. query-docs(query="WebSocket implementation")
  3. 基于最新文档生成代码

总结与行动指南

核心要点回顾

AIDD 的五大支柱:

1. 项目记忆系统:
   - 模块化文档架构
   - 90% 上下文效率提升
   - 持续更新机制

2. 专用 Agent 系统:
   - 领域专业化
   - Handoffs 工作流
   - 高效协作模式

3. MCP 工具集成:
   - 文档优先原则
   - 运行时验证
   - 浏览器自动化

4. Agent Skills:
   - 可复用任务模板
   - 标准化工作流
   - 快速调用机制

5. 自动化工作流:
   - 质量保证
   - 安全检查
   - 性能优化

最后的建议

给团队领导者:

1. 投资基础设施:
   - 文档系统是核心
   - 不要急于求成
   - 持续优化迭代

2. 培养 AI 思维:
   - 鼓励团队使用 AI 工具
   - 分享最佳实践
   - 建立学习文化

3. 衡量和优化:
   - 跟踪效率指标
   - 识别瓶颈
   - 持续改进

给开发者:

1. 拥抱 AI 工具:
   - 学习使用专用 Agent
   - 掌握 Skills 快捷方式
   - 利用 MCP 工具

2. 贡献知识:
   - 更新文档
   - 分享经验
   - 创建新 Skills

3. 保持好奇:
   - 探索新工具
   - 尝试新模式
   - 推动创新

三阶段方法论

原视频链接

第一阶段：研究。我会把所有相关的东西都提供给 AI，包括架构图、文档、Slack 对话记录。

这一点我其实已经反复强调过很多次了，但核心只有一句话：尽可能把所有与你即将做出的修改相关的上下文一次性带进来，然后再使用智能代理去分析整个代码库，梳理系统的组成部分以及它们之间的依赖关系。

这绝对不是一次性完成的过程。我通常会不断追问，比如缓存是怎么处理的？失败场景是如何应对的？如果它的分析有误，我会直接纠正；如果它缺少关键信息，我就补充上下文。每一轮交互，都会让它的分析更加精细。

这一阶段的产出是一份完整的研究文档：系统里目前都有哪些东西、它们之间是如何相互连接的、你即将做出的改动会影响到哪些部分。原本需要花上好几个小时甚至更久的探索过程，被压缩成了几分钟的阅读时间。

我知道 Dex 之前也提到过这一点，但我还是要强调：这里的人工检查点（human checkpoint）至关重要。这是整个流程中投入产出比最高的时刻，你需要把分析结果与现实系统进行对照，在这里发现错误的话就能避免之后发生的灾难性后果。

第二阶段：制定可以“照着做”的实现计划。已经有了可靠研究结论的前提下，我们开始制定一份极其详细的实现计划，包括真实的代码结构、函数签名、类型定义、数据流等。

这份计划的目标，是做到任何一名开发者都可以直接照着执行。我常把它比作“数字填色”：你可以把它交给团队里最初级的工程师，对他说“照着这个来做”。只要他逐行照抄，最终结果就应该是正确可用的。

大量关键的架构决策，正是在这一阶段完成的。我们会在这里确保复杂逻辑是正确的，业务需求遵循良好实践，服务边界清晰，职责划分干净，同时避免任何不必要的耦合。之所以能在问题发生之前就识别它们，是因为我们曾经亲身踩过这些坑。而 AI 并没有这种经验，它会把代码中看到的每一种模式，都当作“必须遵守的约束”。

这一阶段真正的“魔法”，在于评审速度。我们可以在几分钟之内完成对整个方案的验证，并且清楚地知道接下来到底会构建出什么。而如果我们想跟上代码生成的速度，就必须以同样快的速度理解自己正在做的事情。

第三阶段：实现。最后才是实现，一旦我们有了清晰的研究结论和明确的实现计划，这一步反而应该是最简单的，而这正是我们希望看到的结果。

当 AI 有一份清楚、具体的规格说明可以遵循时，上下文就会保持干净且聚焦。我们避免了冗长对话导致的复杂度螺旋。相比五十轮不断“进化”的代码修改，现在只需要三次高度聚焦的输出，而且每一步都会在进入下一阶段前完成验证。没有被放弃的方案，没有相互冲突的模式，也不会再出现那种“等等，其实应该这样”的瞬间，没有留下遍地的死代码。

在我看来，这种方法真正的好处是：你可以把大量工作交给后台运行的智能体来完成。因为所有真正困难、需要动脑子的事情，已经提前由你完成了。智能体只需要按照计划开始实现。你可以去处理别的事情，回来时只需要快速评审结果，因为你检查的只是“它是否遵循了计划”，而不是试图弄清楚它是不是凭空“发明”了什么。

我们不是用 AI 来替我们思考，而是用它来加速机械性的工作，同时保持我们对代码的理解能力。研究更快了，规划更全面了，实施也更干净了。但思考、综合和判断，仍然是我们的责任。

还记得我之前说的那个 AI 无法处理的授权系统重构吗？现在我们实际上已经开始推进它，并且取得了一些实质性的进展。但这并不是因为我们找到了更好的提示词，恰恰相反，我们发现，连研究、规划、实现这些阶段都无法一开始就交给 AI。最终，我们不得不亲自下场，手工完成这次修改：不借助 AI，只是阅读代码、理解依赖关系，然后一步步改动，看哪里会出问题。

说实话，这次人工迁移过程非常痛苦，但至关重要。它揭示了所有隐藏的约束条件、必须遵守的不变式，以及一旦授权逻辑发生变化，哪些服务会直接崩溃。这些信息，是任何自动化代码分析都不可能替我们挖掘出来的。

然后，我们把这个手动迁移的拉取请求纳入了研究过程，让它作为后续所有研究工作的基础。即便如此，由于不同实体之间仍然存在差异，我们还是需要不断追问：这个该怎么处理、哪些数据是加密的哪些不是，每一次都要补充额外的上下文，并经过多轮迭代。

直到这时，我们才有可能生成一份“或许能一次成功”的计划。注意，这里的关键词是“或许”。我们仍然在持续验证、不断调整，并持续发现新的边界情况。

这套三阶段方法并不是什么魔法。它之所以能奏效，只是因为我们曾经亲手完成过一次迁移。在把理解写进流程之前，我们必须先赢得这种理解。

我依然认为，并不存在所谓的银弹。没有更好的提示词，没有万能的模型，甚至也不是写得更漂亮的规格文档。真正重要的，始终是那件最朴素、也最困难的事情：足够深入地理解你的系统，理解到你可以安全地对它做出修改为止。

那为什么还要折腾这一整套流程呢？为什么不干脆一直和 AI 反复迭代，直到“能用”为止？反正模型迟早会变得足够强，最后不就都能跑起来了吗？

在我看来，“能跑”本身并不够。通过测试的代码和能在生产环境长期稳定运行的代码之间，是有本质区别的；今天还能工作的系统，和未来还能被别人安全修改的系统，也是两回事。

这中间存在一个认知鸿沟。当 AI 可以在几秒钟内生成成千上万行代码时，理解这些代码却可能要花你几个小时；如果系统足够复杂，可能需要几天；甚至在极端情况下，你可能永远都无法真正理解它。

软件，终究是一项人类的事业

还有一个我觉得几乎没人认真讨论过的问题：每一次为了跟上生成速度而跳过思考，我们失去的并不只是对代码的理解。我们正在逐渐丧失一种能力：识别问题的能力，那种会提醒你“等等，这里开始变复杂了”的直觉，如果你长期不真正理解自己的系统，是会慢慢退化的。

模式识别（pattern recognition）来源于经验。我一眼就能看出某种架构是危险的，那是因为我就那个曾经凌晨三点还在被它折磨的人；当我坚持推动更简单的方案时，是因为我曾经接手并维护过别人留下的复杂系统。

AI 只会生成你让它生成的东西，它并不会内化那些来自失败的教训。

三阶段方法，正是用来弥合这道鸿沟的。它把“理解”压缩成一系列可以在生成速度下被快速审查的产出物。如果没有这一层，我们只是在用一种自己无法理解的速度，不断累积复杂度。

AI 确实彻底改变了我们写代码的方式，但坦率地说，我并不认为但它并没有改变软件失败的根本原因。每一代人都会遭遇属于自己的软件危机。Dijkstra 那一代，通过建立软件工程这门学科来应对；而我们这一代，面对的是无限规模的代码生成。

答案并在于下一个工具或新的方法论，而在于重新记起一个我们早就知道的事实：软件始终是一项人类的事业。困难的从来不是敲代码，而是在一开始就知道该敲什么。

最终能够走得更远的开发者，并不只是那些生成代码最多的人，而是那些仍然理解自己在构建什么、能够看清系统接缝、敢于质疑问题本身是否正确的人。

我想用一个问题来结束今天的分享，这个问题并不是“我们会不会使用 AI”，那早已是既定事实。

真正的问题是： 当 AI 写下大部分代码的时候，我们是否仍然理解自己的系统？

从清晰的计划开始：先写方案，再写代码

不要只是把“愿望”一股脑丢给 LLM，应先定义问题，再规划解决方案。

一个非常常见的错误，是在提示语还很模糊的情况下，直接让 AI 生成代码。在我的工作流中（以及许多成熟实践中），第一步并不是写代码，而是和 AI 一起头脑风暴，产出一份详细的规格说明，然后再整理出清晰的分步计划。

对于一个新项目，我通常会先描述整体想法，并让 LLM 不断向我反问，直到需求、边界条件和潜在的边缘情况都被充分挖掘出来。最终，我们会把这些内容整理成一份完整的 spec.md，其中包含：功能需求、架构决策、数据模型，甚至测试策略。这份规格文档会成为整个开发过程的基石。

接下来，我会把这份 spec 交给一个具备推理能力的模型，让它生成项目计划：把实现过程拆解成逻辑清晰、粒度合适的小任务或里程碑。某种意义上，这是一个“迷你版设计文档 / 项目计划”。我通常会多次迭代这份计划——亲自修改，再让 AI 批判性地审视、优化——直到它足够完整、连贯，然后才进入真正的编码阶段。

这种前期投入乍看之下有点慢，但回报极高。正如 Les Orchard 所说，这就像是“15 分钟完成一次瀑布式设计”，一个快速而结构化的规划阶段，让后续编码变得异常顺畅。

有了清晰的规格和计划，当我们真正“释放”代码生成能力时，人和 AI 都非常清楚：我们要做什么，以及为什么要这么做。简而言之，先规划能让你和 AI 站在同一页上，避免无效反复。很多人会跳过这一步，但如今有经验的 LLM 开发者，已经把高质量的 spec / plan 当成整个工作流的核心。

把工作拆分成小而可迭代的块

范围管理是一切的关键：给 LLM 可控的小任务，而不是一次性塞进整个代码库。

我学到的一个重要教训是：不要让 AI 一次性输出大量、整体性的代码。相反，应把项目拆成一系列小步骤或“工单”，逐个完成。这本来就是良好的软件工程实践，但在引入 AI 之后变得尤为重要。

LLM 在聚焦型任务上表现最好：实现一个函数、修复一个 bug、添加一个小功能。比如在完成规划后，我会直接对代码生成模型说：“好，我们来实现计划里的第 1 步。”完成后测试，再进入第 2 步，如此循环。每一个 chunk 都足够小，小到 AI 能在上下文中处理干净，而你也能真正理解它生成的代码。

这种方式能有效防止模型“跑偏”。如果一次性要求太多，模型往往会迷失方向，生成一堆“纠缠在一起的代码垃圾”，非常难以维护。很多开发者都有类似体验：让 LLM 一口气生成一个完整应用，结果代码风格不统一、逻辑重复，“就像 10 个程序员各干各的，彼此完全没沟通”。我自己也踩过这个坑，解决方法只有一个：停下来，退一步，把问题切小。

每一轮迭代，我们都在已有上下文的基础上，增量式地推进。这也非常适合测试驱动开发（TDD）：每一步都可以同步编写或生成测试（后面会详细讲）。

不少编码 Agent 工具已经显式支持这种“分块”工作流。例如，我有时会生成一个结构化的“prompt plan”文件，里面包含每个任务对应的一条提示语，让 Cursor 这类工具按顺序逐条执行。核心原则只有一个：避免大跃进。通过小步快跑，我们大幅降低灾难性错误的概率，也能更快纠偏。LLM 在快速、受限的任务上非常擅长，要顺势而为。

提供充足的上下文和明确的指导

LLM 的质量上限，取决于你提供的上下文质量。把相关代码、文档和约束条件都给它。

在处理真实代码库时，我会确保 AI 拥有完成任务所需的一切信息：相关源码、技术约束、已知坑点、推荐或禁止的方案。现代工具在这方面已经很强了：比如 Claude 的 Projects 模式可以直接导入整个 GitHub 仓库；Cursor、Copilot 会自动把当前打开的文件放进上下文。但我通常还会做得更多。

如果我怀疑模型缺乏某些关键信息，就会通过 MCP（比如 Context7），或干脆手动把重要模块、API 文档粘进对话里。资深 LLM 用户普遍强调这种“上下文打包（context packing）”的重要性，比如在编码前来一次完整的“信息倾倒”，包括：

高层目标与不变量

正确解法的示例

明确警告哪些方案不要用

如果任务本身比较棘手，我甚至会提前告诉 AI 哪些朴素解法性能不行，或者给它一个外部参考实现。如果使用的是冷门库或全新 API，我会直接贴官方文档或 README，避免它“蒙着眼睛飞”。

所有这些前置上下文，都会显著提升输出质量，因为模型不需要猜测，而是基于事实和约束进行生成。

现在也有不少工具能自动化上下文整理，比如 gitingest、repo2txt，它们可以把代码库的关键部分导出成一个文本文件，让 LLM 一次性读入。对于大型项目来说，这是救命工具。原则很简单：不要让 AI 在信息不完整的情况下工作。一个 bug 如果涉及四个模块，就把这四个模块都给它。当然要注意 token 限制，但如今前沿模型的上下文窗口已经非常大（几万 token），合理利用即可。我通常只选取与当前任务相关的代码，并明确告诉 AI 哪些内容可以忽略，以节省上下文空间。

我个人也很看好 Claude Skills 这个方向：它把原本脆弱、一次性的提示，封装成可复用的“技能”，把指令、脚本和领域知识模块化。当请求匹配某个 Skill 时，工具可以自动应用这些能力，效果远好于通用 prompt。这让我们从一次性交互，走向可复用、可沉淀的工程流程。

目前社区已经有不少 Skills 集合，我很喜欢的一个例子是 frontend-design skill，它能终结 LLM UI 里泛滥的“紫色设计风”。在官方工具全面支持之前，也已经有一些可行的变通方案。

最后，在 prompt 里用明确的注释和规则引导 AI。例如，我会在代码前加一句：“这是 X 的当前实现，我们需要扩展它来做 Y，但一定不要破坏 Z。”这种小提示非常有效。LLM 本质上是“字面主义者”，你给什么指令，它就照着执行。上下文越清晰，幻觉和跑偏就越少，生成的代码也越贴合项目实际。