AI Coding 的个人实践 ​

这里记录我在 AI Coding 模式下的个人实践要点。

这份手册综合了官方实践（Cursor 的 agent best practices、harness engineering 相关文章）、直播/教程里反复出现的方法，以及社区复盘里最稳定、最可复用的技巧，不走“纯玄学流”。

模型选择 ​

GPT 与 Claude 搭配最佳 ​

个人用 GPT-5.4 处理需求分析、实现方案、调试思路和多工具任务，再把 Claude Opus 4 用在核心模块编码、重构和高难修复上，最后用 GPT-5.4 做 PR 审查和总结。

Harness Engineering 实践经验 ​

核心原则 ​

Vibe coding 真正高效的前提，不是“把活全丢给 AI”，而是把开发变成“规格明确、小步推进、快速验证、随时回退”的闭环，这一点在 Cursor 官方指南、社区教程和经验复盘里高度一致。

你可以把 AI 当成一位速度很快但容易过度发挥的工程师：它适合在清晰目标和强反馈下工作，不适合在模糊目标、超长上下文和弱验收下自由发挥。

因此整套手册只有一句总原则：先定义，再生成；先验证，再继续；先回退，再补救。

开工前 ​

做好约束 ​

项目层面准备一份常驻规则文件，写清构建命令、测试命令、代码风格、目录约束、禁改区域和典型参考文件；规则要短、稳定、普适，不要把整本规范手册塞进去 —— 对应 SDD 中的 Constitution。

每个需求都先产出一份轻量 spec，社区里：Kiro spec 模式、Superpowers.spec、Speckit.specify 都可。

Rules 约束 ​

项目 rules（如 AGENTS.md、Cursor rules）与 Constitution、轻量 spec 保持一致，避免口头约定与自动化检查脱节。

单次工作流 ​

把每次开发都固定成 6 步：写计划、确认计划、只做一个最小改动、立刻测试、看 diff、再决定继续还是回退，这种“小步快跑”是教程、官方文档和社区指南里出现频率最高的模式。

遇到 bug 时，不要自己转述一大段，而是把报错、截图、复现步骤和期望行为直接交给 AI；Karpathy、Cursor 官方和多份教程都强调，原始错误信息和视觉上下文往往比抽象描述更有效。我一般喜欢用 Superpowers.system-debugging 基于根因分析流程，禁止“试试看”式修复。

上下文管理 ​

上下文是 vibe coding 最容易失控的地方，多个来源都明确提到：对话一长、工具一多、无关文件一多，模型就会开始失焦、重复犯错，甚至进入“越聊越笨”的状态。

实操上建议这样管：一个 chat 只做一个功能或一个 bug；一旦 AI 开始反复犯同样错误、或者上下文明显变脏，就立刻开新会话。

不要把整个仓库和所有说明一次性塞进去，而是用“项目规则 + 当前任务 spec + 少量相关文件 + 必要截图/日志”的组合；如果需要更复杂的探索，把研究、实现、调试拆给不同子任务或子 agent，当作上下文隔离手段而不是角色扮演游戏。

质量门禁 ​

每次改动后跑最小测试集、成功时静默失败时才回显错误、频繁 commit、保留 checkpoint/回滚点、关键配置文件和高风险代码必须人工 review。

更进一步的成熟做法是加 hooks 和 reusable skills：例如在 agent 停止时自动触发 typecheck、自动拒绝危险命令、把“实现新接口”“补测试”“开 PR”做成固定工作流，而不是每次临场发挥。

项目记忆分层（上下文管理） ​

这套方法要解决的不是“怎么让 AI 记住所有东西”，而是“怎么把高价值上下文分层放到上下文窗口之外，并在合适时机再拉回来”，因为官方最佳实践已经把结构化笔记、文件化记忆、项目规则文件和决策记录视为长任务稳定性的关键手段。

Anthropic 明确推荐 structured note-taking 与 file-based memory，LangChain 将这类做法总结为 write、select、compress、isolate，而 Microsoft 则把 ADR 定义为持续维护的 append-only 决策记录。

因此，这份文档采用四层结构：notes 记录当前任务状态，memory/ 沉淀跨任务知识，AGENTS.md 保存稳定规则，ADR 记录重大技术决策。

四层分工 ​

四层不要混写，因为它们分别服务于不同时间尺度：notes 面向当前任务连续性，memory/ 面向跨任务复用，AGENTS.md 面向稳定项目约束，ADR 面向长期可追溯的技术取舍。GitHub 对 agent skills 的定义也说明，稳定规则和专项流程适合被写成可按需注入的 Markdown 指令，而不是每次靠口头重讲。

实际落地时，判断顺序可以固定为：这是当前任务状态就进 notes，这是以后还会复用的知识就进 memory/，这是长期稳定规则就进 AGENTS.md，这是重要技术取舍就进 ADR。

与 AI 协作 ​

真正能让团队用起来的关键，不是“有这些文件”，而是给 AI 规定固定的读写节奏，因为每个新会话本质上都是新上下文，而 Claude Code、Copilot 这类系统都需要依赖项目级文件或自动记忆机制跨会话保留知识。

推荐把每个任务固定成四个时点：开工前读规则，执行中更新 notes，多次出现的错误提炼 memory，出现重大方案分歧时起草 ADR。

• 开工前，人对 AI 说：先阅读 AGENTS.md、notes/current.md、相关 spec 和最近 ADR；先总结现状和约束，不要立刻编码。 这样做符合 AGENTS.md 和项目记忆文件的定位，即先完成项目级 onboarding，再开始动作。
• 执行中，人对 AI 说：每完成一个阶段，都更新 notes/current.md 的已完成、下一步、阻塞和临时结论。 这正是 Anthropic 推荐的 structured note-taking 模式，用于把关键状态写到上下文窗口之外。
• 出现多次相同错误后，人对 AI 说：扫描今天的 notes、PR 评论和我对你的纠正，提炼 3-5 条候选长期规则，输出到 memory/candidates-YYYY-MM-DD.md，不要直接改 AGENTS.md。 这和 GitHub agentic memory 的思路一致，即从开发过程里提炼对未来任务有用、且可操作的知识，而不是保存整段聊天历史。
• 出现架构分歧时，人对 AI 说：把当前争议整理成 ADR 草案，写背景、备选方案、决策建议和后果，不要直接视为已接受。 这与 Microsoft 对 ADR 的建议一致：ADR 是决策记录，不是临时任务笔记。

建议团队把“AI 可以自动写什么”也明确下来：notes 允许自动更新，memory 允许自动提炼候选项但要人工确认，ADR 允许自动起草但不自动定案。

这样做的原因是，GitHub Copilot 的 agentic memory 虽然已经支持代码证据校验和自动过期，但官方仍把治理、验证和淘汰当作必要机制，而不是完全放任自动记忆长期积累。

自动化与 skills ​

社区里已经有 create-agentsmd、create-architectural-decision-record、make-skill-template 这类技能，说明生成规则文件、起草 ADR 和搭建技能骨架都已经是成熟场景。

搭配 self-improving-agent 实现自我进化 ​

想要“越用越懂你”、并且确实会长期反复做同类任务建议搭配使用。

记录三类内容：

• 你明确纠正过的错误。
• 反复出现的任务套路或最佳实践。
• 工具失败后的修复办法和注意事项。

这些内容会被写入类似 .learnings/LEARNINGS.md、.learnings/ERRORS.md 这样的文件，方便后续复用。

推荐工作流

如果你想把它用得更稳，建议按这个顺序：

1. 先让它做任务。
2. 发现问题就立刻查看 learnings 纠正。
3. 让它把纠正转成可复用规则。
4. 在重大任务前先回看已有 learnings。

仓库模板 ​

下面这套结构适合先作为团队最小可用版本。

/
├─ AGENTS.md
├─ notes/
│  ├─ current.md
│  └─ archive/
├─ memory/
│  ├─ README.md
│  ├─ coding-conventions.md
│  ├─ domain-glossary.md
│  ├─ known-pitfalls.md
│  └─ candidates/
└─ docs/
   └─ adr/
      ├─ ADR-000-template.md
      └─ ADR-001-*.md

SubAgent 个人实践 ​

适用场景（官方 + 社区共识） ​

1. 需要独立上下文窗口

   • 要做大规模阅读 / 搜索 / 探索（扫代码库、看大量文档、长链调试）。
   • 不希望把一堆中间过程（log、搜索结果、分析推理）污染主会话上下文。

2. 任务自包含，有清楚的输入输出

   • “给你一坨输入，自己搞完，最后给我一个结果或总结”。
   • 例：代码安全审计、SQL 变更评估、性能问题分析。

3. 需要专门角色 / 人设

   • 专门的：Code Reviewer、Security Auditor、Data Analyst、Researcher。
   • 有独立 system prompt、自己的工具权限和风格，而不是主 Agent 简单换个语气。

4. 要并行处理多路任务

   • 多个模块 / 仓库 / 微服务同时扫描。
   • 多份文档并行总结或交叉验证。

5. 高风险操作需要隔离

   • 数据库变更、CI/CD 部署、生产配置修改，先让 “DB-Reviewer” subAgent 评估再执行。

不满足这些，而只是“想固定流程”“想更听话”，先上 Skill，通常更轻。

SubAgent 的设计原则 ​

单一职责（Single Responsibility） ​

• 一个 SubAgent = 一个角色 + 一个清晰目标：输入是什么、要做哪一步、输出给谁。
• 描述写得像“Job Description”，而不是“会很多事的 AI”：
  • ✅ 「已有完整 spec & plan 后，审查实现方案，给出风险 & 改进建议。」
  • ❌ 「很懂代码、可以帮忙 review、也能写代码、也能部署。」

清晰的输入/输出与接力约定 ​

• 在定义 SubAgent 时，把这三件事写死：
  1. 什么时候触发（前置条件）；
  2. 需要的输入（主 Agent 提供什么）；
  3. 输出格式（给主 Agent 什么结构）。
• 输出最好是结构化，比如 JSON / Markdown 小节，让主 Agent 容易继续编排：

{
  "summary": "...",
  "risks": ["...", "..."],
  "recommendations": ["...", "..."],
  "next_steps_for_main_agent": ["...", "..."]
}

与 Skill / 主 Agent 的关系 ​

先 Skill，后 SubAgent ​

社区实践共识：先用 Skill 固定“怎么做”，再用 SubAgent 换“谁来做”。

• Skill：把 workflow / checklist / pattern 写清楚，主 Agent 或 SubAgent 都可以复用。
• SubAgent：把某个角色连同其使用的 Skill 绑定起来，比如：
  • spec-workflow skill → 主 Agent 跑。
  • plan-review skill → Review SubAgent 跑。
  • security-checklist skill → Security SubAgent 跑。

何时让主 Agent 做，何时让 SubAgent 做 ​

• 主 Agent：需要逐步可见的操作、用户随时插话干预、强交互流程。
• SubAgent：长时间、不需要中途对话的计算/分析任务，或者你只想收一份最终报告。

典型架构模式 ​

综合多篇 “agentic workflow / multi-agent patterns” 文章，可以提炼出几个常用模板。

领导者 + 专家型（Coordinator + Specialists） ​

• 主 Agent = Coordinator：拆解任务、挑选 subAgent、收敛结果。
• SubAgents = 专家：Code Reviewer、DB Specialist、UX Writer、Researcher 等。
• 优点：结构清晰，像微服务架构，适合生产系统；缺点是需要你设计好角色边界。

Sequential Pipeline（顺序流水线） ​

• 按阶段串起来：Research SubAgent → Draft SubAgent → Critic SubAgent → Polisher SubAgent。
• 适合：文档生成、报告写作、多阶段转化（原始数据 → 摘要 → 报告 → 幻灯片）。

Parallel Workers（并行工人） ​

• 多个 SubAgent 同时处理不同文件、模块或角度，然后主 Agent 汇总。
• 适合：大仓库扫描、性能 profiling、日志分析、评审多个 PR。

社区常见坑与反模式 ​

汇总官方 + 社区踩坑文档中的常见问题：

1. SubAgent 干的事情太泛

   • “万能助手”式 SubAgent，会和主 Agent 角色重叠，调度混乱。
   • 解决：写死单一职责，明确只在某个阶段 / 某种任务被启用。

2. 描述不清，导致路由混乱

   • 描述里没讲清楚“何时用我”“我产出什么”，自动路由就模糊。
   • 解决：在 description 里写触发条件 + 输出形式，如：“当已有完整实现代码时，用我做安全审计，输出风险列表 + 说明”。

3. 把需要强交互的任务丢给 SubAgent

   • 比如需要不断向用户问问题、确认细节的任务，SubAgent 中途不能和用户对话，体验会很差。
   • 解决：这类任务留给主 Agent，用技能 / prompt 去约束流程即可。

4. 上下文泄漏 / 混乱

   • 主 Agent 中塞了太多前置调研，再开 SubAgent，反而信息重复、token 浪费。
   • 解决：把“读很多东西再总结”的步骤直接放到 SubAgent 里，让主 Agent 只传关键信号。

5. 过度多 Agent / 过早多 Agent

   • 一上来就设计一大堆 Agent Team / Graph，结果维护成本巨大，还不好 debug。
   • 解决：从“一个主 Agent + 1–3 个 SubAgent”开始，先让关键角色跑顺，再考虑更复杂图。

SubAgent 落地建议（给你直接用的 checklist） ​

社区里推一套 SubAgent 实践，可以直接用下面这套最小化方案。三问有两个答「是」，优先考虑 SubAgent；否则更多用 Skill。

1. 从 2–3 个 SubAgent 起步

   • Repo-Explorer：负责扫仓库、文档探索、生成结构地图。
   • Code-Reviewer：负责代码评审、风险分析、改进建议。
   • Security-Analyst（可选）：负责高风险改动前的评估。

2. 为每个 SubAgent 写清 4 件事

   • 触发条件（When）
   • 输入内容（Input）
   • 使用的工具 / Skills（Tools/Skills）
   • 输出结构（Output schema）

3. 主 Agent 只做三件事

   • 整体任务拆分 & 调度谁上场。
   • 汇总各个 SubAgent 报告。
   • 负责最终写文件 / 改代码 / 实际执行。

4. 每条新工作流先问自己 3 个问题

   • 这个任务是否需要大量阅读 / 探索？
   • 是否可以自包含完成，有明确输入输出？
   • 是否适合独立角色处理 + 对用户透明？