Agentic Coding — 全自动 AI 编程工作流

概述

本 skill 编排从「想法」到「PR」的完整 AI 编程流程。人只在 4 个关键节点把关，其余环节 AI 自主完成。

4 个人工检查点：

1. 确认需求（PRD）
2. 选定技术方案
3. 判断测试充分性
4. Review PR → Merge

工具链：

• Product-Manager-Skills（deanpeters）：深度需求发现
• cc-sdd：技术规格化 + 自主实现
• 两者都缺失时有内置降级方案

第零步：环境检测

每次触发时，先执行以下检测（静默执行，不需要用户操作）：

依赖检测

检查以下工具是否已安装：

1. Product-Manager-Skills：检查 /skills 列表中是否有 discovery-process 或 prd-development
2. cc-sdd：检查项目中是否有 .claude/skills/ 下的 kiro-discovery 相关文件，或 /skills 中是否有 /kiro- 前缀命令

如果缺失，告知用户：

检测到以下工具未安装，建议安装以获得最佳效果：

[如果缺 Product-Manager-Skills]
→ 需求发现工具：npx skills add https://github.com/deanpeters/Product-Manager-Skills

[如果缺 cc-sdd]
→ 技术规格工具：npx cc-sdd@latest --claude-skills --lang zh

是否现在安装？（不安装也可以继续，将使用内置简化流程）

项目基础设施检测

检查项目根目录：

1. CLAUDE.md 是否存在 → 不存在则在流程开始前引导生成（见附录 A）
2. SPEC.md 是否存在 → 根据流程阶段决定是否需要创建
3. .gitignore 是否存在 → 不存在则生成基础版本
4. 测试框架 是否可用 → 尝试运行测试命令，如果失败则警告

第一步：任务分级

根据用户描述的任务，自动判断规模：

判断方式：根据用户描述中涉及的模块数量、功能复杂度、是否需要新的数据模型或 API 来判断。如果拿不准，按「中」处理。

小任务快速通道：对于小任务，跳到「第四步：编码实现」直接执行，执行前用一句话复述理解让用户确认。

第二步：需求发现（人工检查点 ①）

有 Product-Manager-Skills 时

中型任务：使用 discovery-process workflow 的简化版（重点执行问题定义和方案生成），然后用 prd-development 生成 PRD。

大型任务：使用 discovery-process workflow，执行完整 6 阶段发现：

1. 问题定义（Frame Problem）
2. 用户研究（Conduct Research）
3. 洞察综合（Synthesize Insights）
4. 方案生成（Generate Solutions）
5. 方案验证（Validate Solutions）
6. 决策文档化（Decide & Document）

没有 Product-Manager-Skills 时（内置降级方案）

使用以下结构化采访流程：

第一轮：方向定位（3-5 个问题）

• 这个功能/产品解决什么问题？谁会用？
• 核心场景是什么？用户最常做的 3 件事是什么？
• 有没有参考产品或竞品？和它们的关键区别是什么？
• 时间和资源约束？MVP 还是完整版？
• 最担心什么风险？

第二轮：细节挖掘（针对第一轮答案追问）

• 针对每个核心场景：输入是什么？输出是什么？异常情况怎么处理？
• 用户权限和角色区分？
• 数据从哪来？需要持久化哪些数据？
• 有没有性能、安全、合规要求？
• 需要支持哪些平台/设备？

第三轮：边界确认

• 列出你理解的功能范围，让用户确认
• 列出明确「不做」的东西
• 列出所有假设，逐条让用户确认或修正

质量检查：采访结束后，从以下维度自评需求完整度（0-100）：

• 业务价值清晰度（用户是谁、解决什么问题）
• 功能完整性（核心场景、边界情况、错误处理）
• UX 明确度（输入输出、交互流程）
• 技术约束（性能、安全、兼容性）

如果总分 < 80，针对最弱的维度继续追问，直到 ≥ 80。

需求验证（无论用哪种方式都必须执行）

采访/发现完成后，在生成 SPEC.md 之前必须做：

① 反向复述确认

用自己的话复述理解的需求，重点说清楚：做什么、关键取舍、优先级排序。等用户确认。

② 验收场景

列出 3-5 个具体用户场景："用户 [身份] 在 [情境] 下 → 执行 [操作] → 看到/得到 [结果]"

③ 不做清单

列出明确不在本次范围内的功能和行为，以及判断理由。

④ 分层确认（大任务必用）

大任务不要一口气输出完整 SPEC，先确认目标与范围，再展开行为细节，最后确认边界与取舍。

输出 SPEC.md

验证通过后，生成 SPEC.md，必须包含以下结构（SCOPE 框架）：

# [功能名称] 规格文档

## 目标与范围
[一句话描述这个功能做什么]

### 不做清单
- [明确不在范围内的功能 1]
- [明确不在范围内的功能 2]

## 验收场景
[用 EARS 语法写验收标准]
- When [触发条件], the [系统] shall [行为], within [约束]
- While [状态], the [系统] shall [持续行为]

## 功能行为
### [场景 1]
- 输入：[具体输入]
- 输出：[具体输出]
- 异常：[错误处理]

## 技术约束
[性能、安全、兼容性要求]

## 任务拆解
[实现顺序，标注依赖关系]

## 变更记录
- [日期] v1.0 初始版本

→ 人工检查点 ①：将 SPEC.md 交给用户确认。用户确认后进入下一步。

第三步：技术设计（人工检查点 ②）

有 cc-sdd 时

执行 /kiro-spec-design，让它生成技术设计文档。

没有 cc-sdd 时（内置降级方案）

基于 SPEC.md，提出 2-3 个技术方案：

## 技术方案对比

### 方案 A：[名称]
- 技术栈：[具体技术]
- 优势：[1-2 条]
- 劣势：[1-2 条]
- 适合场景：[什么情况下选这个]
- 预估工作量：[大致范围]

### 方案 B：[名称]
...

### 建议
[说明推荐哪个方案及理由，但明确这是建议不是决定]

角色边界（本阶段硬约束）

• 必须提供 2-3 个方案，禁止只给一个
• 禁止在用户选定前开始写任何实现代码
• 架构复杂度必须匹配项目实际规模（不要给简单应用推荐过度复杂的架构）
• 如果用户没有技术背景，用通俗语言解释每个方案的影响

→ 人工检查点 ②：用户选定技术方案。选定后将决策写入 SPEC.md 的「技术约束」部分，后续实现不得偏离。

第四步：编码实现

启动新 session

重要：编码实现应在新 session 中执行，保持 context 干净。

读取 SPEC.md，按照规格要求完整实现。
实现完成后运行测试确保全部通过，然后提 Draft PR。
如果遇到 SPEC 中的歧义，记录到 CHANGELOG.md 并跳过，不要猜测。

有 cc-sdd 时

执行 /kiro-spec-tasks 拆解任务，然后 /kiro-impl 自主实现。

没有 cc-sdd 时

按 SPEC.md 中的任务拆解顺序逐个实现，每个任务：

1. 阅读相关代码，理解当前状态
2. 实现功能
3. 运行测试命令验证
4. 如果测试失败，分析原因并修复，最多重试 3 次
5. 3 次后仍失败，记录到 CHANGELOG.md 并跳过
6. 测试通过后 commit

角色边界（本阶段硬约束）

• 不得偏离已确认的 SPEC.md
• 不得增加 SPEC 中未定义的功能
• 遇到 SPEC 中的歧义，记录问题并跳过，不要猜测
• 自动修复循环最多 3 次
• 不得修改已有测试使其适配新代码
• 不得修改 .env 文件或 main/master 分支

TDD 策略

不要在 prompt 中教 AI TDD 流程（研究表明这会浪费 context 并增加回归率）。正确做法：

• 实现功能后，运行指定的测试命令
• 测试不过则分析失败原因并修复
• 关注测试是否验证业务意图，而非追求覆盖率数字

Context 管理

• 每 30 分钟或感觉响应变慢时，将进展写入 CHANGELOG.md 然后 /compact
• 复杂的代码分析任务使用 subagent（"use subagent to analyze X"），保护主 session context
• 多任务并行时使用 worktree 隔离（每个任务一个分支）

第五步：测试审查（人工检查点 ③）

实现完成后，向用户展示：

1. 所有测试的运行结果
2. 测试覆盖的核心场景列表
3. 未覆盖的已知边界情况（如果有）

→ 人工检查点 ③：用户判断测试是否充分。如果不充分，补充测试后重新验证。

第六步：Code Review + PR

自审

Agent 完成编码后自审一遍，检查：

• 是否符合 SPEC.md 要求
• 是否有明显的安全问题
• 是否有冗余代码可以简化

提交 Draft PR

• Branch：claude/{feature-name}
• Description：列出所有变更、测试结果、关联的 SPEC.md
• 更新 CHANGELOG.md

claude-code-action（如果配置了）

GitHub Action 会自动在 PR 上留下 Review 评论，作为额外审查。

→ 人工检查点 ④：用户 Review PR，确认后 Merge。

夜间/自主模式

如果用户要求夜间自主执行（通过 Routines 或 headless 模式），使用以下增强约束：

## 夜间任务约束

读取以下文件了解上下文：
- SPEC.md（需求规格）
- CLAUDE.md（编码规范和角色边界）
- CHANGELOG.md（历史进展）

对每个任务：
1. 阅读相关代码
2. 实现功能
3. 运行测试，失败则修复（最多 3 次）
4. 全部通过后 commit

如果任务无法完成：
- 在 CHANGELOG.md 记录失败原因和已尝试方案
- 跳过，继续下一个任务
- 不要猜测解决方案

完成后：
- 创建 Draft PR，branch: claude/tonight-{date}
- 更新 CHANGELOG.md

约束：
- 不修改已有测试
- 不修改 .env 或依赖文件
- 不合并 PR
- 不部署到生产环境
- 每个任务一个 commit

上下文接力（CHANGELOG.md 格式）

长任务跨 session 时，使用以下格式记录：

# CHANGELOG.md

## [日期] [Session 描述]

### 完成
- [x] [完成的任务 1]
- [x] [完成的任务 2]

### 阻塞
- [ ] [阻塞的任务]：[阻塞原因]

### 失败方案记录
- [尝试了什么] → [为什么失败]

### 环境状态
- 当前分支：[branch name]
- 依赖变动：[有/无]
- 未提交的改动：[有/无]

### 下次继续
- 从 [具体任务] 开始
- 注意 [需要关注的问题]

附录 A：CLAUDE.md 模板

当检测到项目缺少 CLAUDE.md 时，引导用户生成。询问项目名称、描述、技术栈后，生成以下内容：

# CLAUDE.md

## 项目概述
[项目名称]：[一句话描述]

## 技术栈
[根据用户输入填写]

## 构建与运行
- 安装依赖：[命令]
- 开发服务器：[命令]
- 测试：[命令]
- Lint：[命令]

## 项目结构
[让 Claude 扫描后自动填写]

## AI 角色边界（硬约束）

### 需求发现阶段
- 禁止提及具体技术栈或实现方案
- 禁止替用户做产品判断
- 只能提问、记录、结构化整理
- 可以指出遗漏场景，但必须以提问形式

### 技术设计阶段
- 必须提供 2-3 个方案并分析利弊
- 禁止在用户选定前开始实现
- 架构复杂度必须匹配项目实际规模

### 编码实现阶段
- 不得偏离已确认的 SPEC.md
- 不得增加未定义的功能
- 自动修复最多 3 次

### Code Review 阶段
- 不得自动合并 PR
- 不得修改已有测试

## 编码规范
- 使用最简单的实现方式，避免过度抽象
- 所有导出函数必须有注释

## 禁止操作
- 不得删除已有测试文件
- 不得直接修改 main/master 分支
- 不得修改 .env 文件
- 不得在没有测试的情况下提交新功能

## Git 规范
- 分支命名：feature/{描述} 或 fix/{描述}
- Commit message：type(scope): description
- 所有改动通过 Draft PR 提交

## 已知环境限制
- Linux 沙箱无中文字体，SVG 转 PNG 会乱码
- 超过 500KB 的文件不会被索引
- 上下文在 40% 使用率后开始衰减

## 详细规则
细则放在 .claude/rules/ 目录下，按路径匹配加载。

CLAUDE.md 必须控制在 200 行以内。 如果项目信息很多，将详细规则拆分到 .claude/rules/ 目录：

.claude/rules/
├── testing.md      # globs: ["**/*.test.*", "**/*.spec.*"]
├── frontend.md     # globs: ["src/components/**", "**/*.tsx"]
├── api.md          # globs: ["src/api/**", "src/routes/**"]
└── database.md     # globs: ["src/db/**", "**/migration*"]

每个规则文件格式：

---
globs: ["匹配模式"]
---

# 规则标题
- 具体规则 1
- 具体规则 2

附录 B：已知环境限制速查