ai-coding-workflow

AI Coding Workflow

一、设计原理（先理解再使用）

痛点根因：聊天窗口的 context 同时承担两件事：

1. 执行上下文——工具调用、代码生成、推理
2. 业务上下文——需求规格、技术方案、历史对齐

挤在同一块"有限内存"里，执行占用越多业务上下文越少；溢出后自动压缩，关键业务信息丢失。同时，线上 PRD/技术文档 Agent 拿不到，新会话从零开始。

协作痛点：人是单线程的（类比 JS 执行栈），Agent 跑十几分钟人就干等十几分钟。

两条解决思路：

• 业务上下文搬到"存储"：放进 Obsidian 本地知识库，Agent 按需取用并反向迭代维护
• 借鉴 JS 异步：把任务交给 Agent 像发出一个 Promise，不阻塞主线程；多 worktree + 多会话并行，跑完再切回审阅

二、四个核心能力

1. Obsidian 本地化——业务上下文从内存挪到存储

关键决策：AI Agent 的工作目录设在 Obsidian 知识库，不是代码仓库。启动会话即在需求上下文里；需要改代码时通过 frontmatter 的 worktree 字段跨过去。

目录约定：

需求/<需求名>/
├── index.md              ← 需求入口 + frontmatter
├── 草稿区/
│   ├── 人工/             ← 个人思考空间
│   └── AI/               ← AI 生成的初稿（待审阅）
├── 调研/                 ← 按需
├── 教学/                 ← 按需
└── 开发/<模块>/
    ├── 规格.md           ← 交付标准
    ├── 技术方案.md       ← 实现路径
    └── 任务清单.md       ← 可执行拆分 + 执行状态

index.md frontmatter：

type: project
status: 草稿 | 进行中 | 完成
worktree: ~/<repo>-<需求简称>
created: YYYY-MM-DD
prd: https://...        # 可选
api: https://...        # 可选
figma: https://...      # 可选
meego: https://...      # 可选

读到 type: project 即识别为需求文档；worktree 字段是跨到代码仓库的入口。

2. Git Worktree 并行——人和 Agent 不互等

<repo>-source/        ← 主仓库保持干净，只作 worktree 源
<repo>-需求A/         ← worktree A + Claude Code 会话 A
<repo>-需求B/         ← worktree B + Claude Code 会话 B

规则：

• 每个需求一个 worktree，独立 Claude Code 会话
• 多 tab 并行：A 跑着就切到 B 推进
• worktree 路径写在 index.md frontmatter，AI 读一眼即定位
• 需求完成后清理 worktree，更新 status: 完成

收益：需求间物理隔离、上下文不互相污染；分支切换、rush-update 等高成本操作彻底避开。

3. CLAUDE.md 模块化——约束 Agent 行为

分工：CLAUDE.md 定义"怎么做事"，知识库定义"做什么"。

模块化拆分（避免单文件膨胀，通过 @ai/xxx.md 引用）：

CLAUDE.md              ← 入口，引用子模块
ai/
├── meta.md            ← 项目定位、目录结构全貌
├── workflow.md        ← 研发流程（规格驱动、阶段门禁）
├── repo.md            ← 关联代码仓库、worktree 命名约定
├── frontmatter.md     ← 各类文档 frontmatter 约定
├── mermaid.md         ← Mermaid 图规范
├── obsidian.md        ← Obsidian/CLI 使用积累
└── lark.md            ← 飞书 CLI 使用积累

双模式工作（共享同一套规则，只是入口不同）：

• 从知识库出发：工作目录在 Obsidian 库，适合需求梳理、方案设计、调研；通过 worktree 字段跨到代码仓库执行修改
• 从代码出发：工作目录在 worktree，适合深度编码；通过 Obsidian/飞书 CLI 反向读取知识库

跨目录能力是关键——Claude Code 区别于和具体目录耦合的 IDE，一个会话内可同时读写知识库和代码仓库。

4. 飞书 CLI 接入——让线上协作数据进入 Agent

目的：把 PRD、技术文档、会议纪要、项目从线上拉到本地；本地产出回写为在线文档。

关键变化：

• 需求 frontmatter 挂 prd / api / figma / meego 链接，Agent 直接通过 lark-cli 拉取
• 调研、方案产出可一键回写到线上文档，与协作方对齐
• 线上协作数据真正成为 Agent 的可用上下文，不再断链

常用入口：

• lark-cli docs +fetch 读飞书文档
• lark-cli docs +create / +update 写飞书文档
• 其他场景见 lark-* 系列 skill（doc、calendar、im、task、minutes、wiki、base 等）

三、规格驱动开发（spec-driven）

剥开工具谈核心：动手前先把要什么聊清楚。

三阶段门禁

规格（要什么）→ 技术方案（怎么做）→ 任务清单（拆成什么步骤）

每阶段审阅通过才进入下一阶段。写进 CLAUDE.md 即硬规则：

• 给出最佳方案供审阅
• 方案通过审阅前，禁止操作

效果：返工从"推翻重来"变成"调整方案"。

小原子渐进

需求拆成可独立交付的最小模块，每个模块独立走 规格→方案→任务 循环。模块间互不阻塞，做完一个再开下一个。

效果：范围小、上下文集中，AI 不容易跑偏，人也容易审阅。

版本追踪（version + based_on）

# 规格.md
version: 1

# 技术方案.md
version: 1
based_on: 规格v1

# 任务清单.md
version: 1
based_on: 技术方案v1

规则：

• based_on 与上游 version 不匹配 = 需要同步
• 上游变更后，自上而下同步下游

进入检查（硬约束）

每次进入一个开发模块，AI 必须先做的事：

1. 比对三件套的 version 和 based_on
2. 不匹配 → 从同步开始，不往下走
3. 匹配 → 才能进入实际开发

效果：过期方案被自动拦截，不会在错误基础上继续开发。

四、Skill 行为指南

当用户的请求落入以下场景时，按对应动作处理：

场景信号	行动
"开始一个新需求" / "建需求文档"	在 需求/<需求名>/ 下建 index.md，写 frontmatter（含 type: project、status: 草稿、worktree），按需建 草稿区/人工、草稿区/AI
"拉 PRD" / "看一下飞书文档 xxx"	用 lark-cli docs +fetch 拉取；如要沉淀就写到 调研/ 或对应需求目录
"建 worktree" / "开新需求的工作树"	从主源仓 git worktree add 一个 <repo>-<需求简称>，同时更新需求 index.md 的 worktree 字段
"写规格 / 技术方案 / 任务清单"	在 开发/<模块>/ 下建对应文件，frontmatter 含 version 和 based_on（规格.md 除外）
"进入模块开发" / "继续做模块 X"	先比对三件套版本号，不一致先同步；规格/方案未审阅通过禁止改代码
"拆分 CLAUDE.md" / "整理 ai/ 目录"	按 meta / workflow / repo / frontmatter / mermaid / obsidian / lark 模块化拆
"需求完成"	清理 worktree，更新 index.md 的 status: 完成

核心约束（写进 CLAUDE.md 时也是硬规则）：

1. 业务上下文以知识库为事实源，聊天窗口只承载执行上下文
2. 方案审阅通过前禁止动代码
3. 进入模块开发前必须比对版本
4. 多需求并行靠 worktree 物理隔离，不要在同一工作树切分支

五、应用场景

场景	做法
理解存量代码与业务	AI 通读建立全局认知 → 按模块深入 → 产出沉淀到知识库 → 整理无法解析的业务点定向求证
技术调研	AI 检索官方文档与高质量材料 → 聚合为结构化文档 → 针对疑点追问 → 写入知识库按 index.md + 子文档组织
技术方案设计	人工独立产出核心思路 → AI 平行生成参考方案做对比、暴露盲点 → AI 完成排版、数据流图、架构图
需求开发	走完整规格驱动三阶段，每阶段审阅通过；小原子拆分 + worktree 并行执行