小型工程 Vibe Coding 全流程管理方案

核心理念

Claude Code 的本质工作方式是读你仓库里的文字文件，所以「管理 vibe coding」翻译成一句话：

把「约定、计划、任务、验收标准、决策结论」写成文件，放在它会在正确时机读到的地方。

有两个容易混淆的「上下文」，必须先分开：

最常见的翻车姿势，是把「我这次问了啥、AI 怎么答的」这种流水账不断喂回每次会话——上下文膨胀、成本上升、结果还变差。流水交给工具，结论交给文件。

一、项目目录设计

代码层与「AI 协作层」分开，简单工程一开始只要几个锚点：

myapp/
├── README.md              # 项目入口（人先读）
├── CLAUDE.md              # AI 常驻上下文（只认这个名字/位置）
├── .claude/
│   ├── settings.json      # 权限 + hooks（确定性自动化）
│   ├── skills/            # 自定义斜杠命令 + 可复用流程（SKILL.md）
│   └── agents/            # 隔离子代理（按需加）
├── docs/                  # 人和 AI 共享知识库 —— 人写的地图
│   ├── PRD.md             # 产品需求（要做什么、为什么）
│   ├── ARCHITECTURE.md    # 技术方案（怎么做）
│   ├── USER_STORY.md      # 用户故事（按需）
│   ├── DATABASE.md        # 数据设计（按需）
│   ├── API.md             # API 说明（按需）
│   ├── tasks/             # 任务卡 —— 拆解落地处
│   ├── decisions/         # ADR 架构决策记录
│   └── CHANGELOG.md       # 版本变化（按需）
├── src/    
├── tests/
├── ...
└── .git/                  # commit 当回滚点

三个原则：

1. 「人写的地图」和「AI 读的规则」分开：docs/PRD.md（+ ARCHITECTURE.md 等）写「要做什么、为什么」（人审），CLAUDE.md 写「怎么约定、别碰什么」（AI 读）。别把需求堆进 CLAUDE.md。
2. 按需渐进：新项目只要 README + CLAUDE.md + docs/PRD.md + docs/tasks/ + git 就能跑；USER_STORY / DATABASE / API / CHANGELOG 等项目长大再补。等「第三次重复解释同一件事」时再抽成 skill（即自定义命令）。
3. commit 当回滚点：AI 跑偏时靠 git 干净退回。

每个文件的维护节奏（何时写 / 何时读）

一条记录得同时有「何时写」和「何时被读」两个答案，否则就是死档。按更新频率分三档：

骨架（立项建一次，低频改）

持续演进（每个开发循环都碰）

按需补（项目长大才加）

一句话记忆：「要做什么」写 PRD，「为什么」写 ADR，「做到哪」写任务卡，「怎么约定」写 CLAUDE.md，其余按需。

从空文件夹起步（最小集，别铺满）

空壳文件比没有更糟——尤其 CLAUDE.md 常驻加载，一堆空文件白占上下文还误导 AI。所以「缺啥补啥」，不是一次生成全套：

1. git init + 配好 .gitignore（node_modules / .env / build 产物）
2. 写 README.md：一句话 + 怎么跑
3. 写 docs/PRD.md：目标 / 范围 / 验收标准
4. 写 CLAUDE.md：技术栈 + 命令 + 目录约定 + 红线（先手写，有代码后可用 /init 校准）
5. docs/tasks/ 放第一张任务卡：「让骨架跑起来」

之后撞到「这个文件该有了」再补。结构生成两种做法：偶尔开工程用本地模板文件夹复制；经常开工程用 new-project-scaffold 一键生成。

二、上下文维护

分层决策表（什么时候放哪）

CLAUDE.md 的骨架与纪律

骨架建议：

# CLAUDE.md

## 项目概述
一句话：这个项目是什么、解决什么问题。

## 技术栈与命令
- 技术栈：TypeScript + Next.js + Prisma
- 开发：npm run dev / 测试：npm test / Lint：npm run lint

## 目录约定
- src/app/ 放路由，src/components/ 放组件，src/lib/ 放工具

## 编码规范
- 错误用 Result 类型返回，不抛异常
- API 层必须用 Zod 校验入参

## 红线（不碰什么）
- 别改 auth 逻辑，除非我先明确同意
- 别引入新依赖，除非我先确认

维护纪律：

• 控制在 ~200 行内，给它一个 owner，改动像代码一样 review——因为每一行都会加载进每个会话。
• 只在 AI 真的犯错时才加规则（lean and boring），别预防式堆砌；臃肿的上下文可让推理成本上升 >20%。
• 定期删过时内容（context rot），规则过期比没规则更糟。
• 会话内维护：任务切换 /clear 开新会话；长会话 /compact 压缩；复杂任务先进 plan mode。

三、记录与决策管理

工具负责存流水，你负责存结论。

三层落点

关键问题要不要记——判定标准

• ✅ 架构/技术选型及理由 → 记 ADR
• ✅ 踩过的坑 + 解法 → 记在任务卡或 docs/troubleshooting.md
• ✅ 反复出现、值得固化的规则 → 提炼进 CLAUDE.md（第三次出现才提）
• ✅ 需求变更 → 更新 docs/PRD.md（技术选型变 → ARCHITECTURE.md）
• ⚠️ 「今天问了啥」→ 一句话 journal 带过，或干脆不记
• ❌ 完整对话原文 → 不手动记，靠 --resume / /export

ADR 模板（Nygard 风格，很轻）：

# 0001 用 JWT 做认证会话
- 状态：已采纳
- 日期：2026-08-22
- 背景：需要无状态认证，支持多端
- 决策：JWT + refresh token，存 localStorage
- 备选：Session cookie（否决：服务端存状态，扩展差）
- 后果：需处理过期刷新；XSS 风险需 CSP 配合

记录要有「消费路径」

一条记录只有「会被读」才有价值。记进 decisions/ 后，必须在 CLAUDE.md 写一条规则告诉 AI 何时读它：

## 约束
- 涉及认证/session 的改动，先读 docs/decisions/0001-jwt-auth.md
- 涉及 API 的改动，先读 docs/decisions/0002-api-error-format.md

这样记录就从「存档」变成「活跃上下文」，在正确时机被加载，而不是每次都加载。

ADR 的生命周期（结论长期保留）

ADR 是「结论」，和任务卡（过程状态）相反：长期保留、被取代也不删。

• 命名：0001-主题.md（编号 + 短横线主题），如 0001-jwt-auth.md。
• 状态流转：已采纳 → 已取代（by 0005）/ 已废弃。旧 ADR 保留并标注被哪条取代，不删除——它解释了「当时为什么那么选」。
• 何时不写 ADR：改动小、可逆、纯风格偏好——ADR 记的是「为什么选 A 不选 B」，不是流水。

四、提问模板

高频任务固化成 skill，一劳永逸。Claude Code 已将自定义 commands 合并进 skills——.claude/skills/<name>/SKILL.md 是推荐写法（目录名即命令名），旧的 .claude/commands/*.md 仍兼容、同名时 skill 优先：

<!-- .claude/skills/plan/SKILL.md -->
---
description: 先读 docs/PRD.md 和相关文件，列出实现计划（改哪些文件、分几步、每步怎么验证），不写代码。
---
先读 docs/PRD.md 和涉及的文件，列出实现计划（改哪些文件、分几步、
每步怎么验证），写到 docs/tasks/ 下。先别写代码。

<!-- .claude/skills/feature/SKILL.md -->
---
description: 读 docs/PRD.md 对应条目 → 拆任务卡 → 最小改动实现 → 补测试 → 跑测试与 lint 全绿 → commit。
---
读 docs/PRD.md 对应条目 → 拆任务卡 → 实现最小改动 → 补测试 → 跑
npm test 和 npm run lint 全绿 → 提交 commit。一次只做一个任务。

<!-- .claude/skills/fix/SKILL.md -->
---
description: 复现 bug → 定位根因 → 最小修复 → 全量测试 → commit。不确定的 API 查源码别猜。
---
复现 bug（先写失败测试）→ 定位根因 → 最小修复 → 跑全量测试 → commit。
不确定的 API 去查源码/文档，别猜。

<!-- .claude/skills/review/SKILL.md -->
---
description: 不改文件，先自审当前改动：bug、缺的测试、边界情况、安全问题、多余复杂度。
---
别改文件，先自审当前改动：有没有 bug、缺的测试、边界情况、
安全问题、多余复杂度？逐条列出。

<!-- .claude/skills/sync/SKILL.md -->
---
description: 把本次会话沉淀：更新任务卡、补 ADR、提炼规则进 CLAUDE.md。
---
把本次会话沉淀为三件事，直接改文件：
1. 更新 docs/tasks/ 中本次任务卡的状态与验收结果；
2. 若产生架构/技术决策，在 docs/decisions/ 新建一条 ADR；
3. 若发现值得固化的约定或踩坑，追加到 CLAUDE.md 或
   docs/troubleshooting.md（只加必要的，别堆砌）。

万能句式（几乎每个提示都值得塞进去）

• 「先读 X，列出计划，别写代码」
• 「一次只改一件事，改最少的文件」
• 「不确定 API/配置就查文档或源码，别猜」
• 「完成后跑 [命令]，全绿才算完」
• 「别加我没要求的功能，别重构无关代码」
• 收尾三问：「改了什么 / 涉及哪些文件 / 怎么验证」

一个完整的 feature 请求：

实现「用户登录」：先读 docs/PRD.md 的认证章节和相关代码，
列出计划别动手。一次只做这一步，改最少的文件，不确定的 API
查源码。补测试，跑 npm test 全绿后再 commit。

五、任务拆分

铁律：一个任务 = 一次会话能完成 + 一个 commit 能说清 + 一条可验证标准。

拆法：

1. 从 docs/PRD.md 拆：里程碑 → 功能 → 垂直切片。垂直切片 = 先跑通最小闭环（哪怕只有一条主路径），再横向铺开，而不是按「先做完数据库层再做 UI 层」横切。
2. 每个任务写一张任务卡放进 docs/tasks/：

## 任务：登录表单校验
- 阶段：M2-认证（里程碑/功能，扁平目录下靠它归组）
- 目标：邮箱/密码前端校验 + 后端 Zod 校验
- 涉及文件：src/forms/login.ts、src/api/auth.ts
- 验收：非法邮箱/空密码被拦截，错误提示正确
- 验证：npm test -- auth + npm run lint
- 状态：☐ 未开始 / ▶ 进行中 / ☑ 完成

3. 复杂任务先 plan mode：让 AI 出 plan 你审，审完再动手——别让它边想边写。
4. 顺序：骨架（能跑起来）→ 一条垂直切片 → 打磨，每步结束三动作：测试绿 + commit + 打勾。

任务卡怎么存：扁平 vs phase 分组

卡片粒度永远是「一个任务一张卡」（铁律，不变）；phase 只是「可选的分组方式」，两者不冲突：

• 扁平 + 编号（推荐起步）：0001-xxx.md、0002-xxx.md…。归档机制让活跃卡始终很少，不需要目录分组；AI 一次只读当前一张卡，多一层目录对它无增益。
• 扁平 + 阶段字段（折中首选）：每张卡里加一行「阶段：M2-认证」，保留 phase 信息但不加目录层级。
• phase 子目录（任务多了、活跃卡 >10 张才考虑）：tasks/01-骨架/、tasks/02-认证/ 各放若干卡；目录只是「容器」，卡片仍是原子任务。

任务卡的生命周期（完成即归档）

tasks 是「过程状态」不是「结论」——做完就该让位，但别直接删（git 存「代码怎么变」，任务卡存「为什么做 / 怎么验收 / 踩了什么坑」）：

按版本迭代：一个版本做完，该版本任务卡整体扫进 archive/vX.Y/，工作区归零、历史还在。

口诀：未完成留手边，完成的进归档，有价值的升格，垃圾才删。

六、验证回路与心态

• hooks 里配 PostToolUse 自动跑 lint/typecheck（确定性，别靠 AI 自觉）；Stop hook 可阻止 agent 过早宣布完成。
• 高风险改动（认证、支付、删除、迁移）永远自己 review——「agent 提议，你拍板」。
• 模型卫生：强模型做规划/推理，便宜模型做直白编辑，第二个模型 red-team 关键 diff。
• 心态：把 Claude Code 当成「不会累、但偶尔幻觉、可能搞坏一切、需要极清晰指令的初级工程师」。专业价值从「写代码」转移到「写清楚需求、拆好任务、审好 diff」。

git 管理（commit 当回滚点）

git 是 AI 的保险丝——不追求完美历史，只追求「随时回到上一个好的状态」。

• 三条铁律：一卡一 commit（message 带任务编号）；测试绿才 commit（配合 hooks）；人审 git diff、人扣扳机（AI 改代码，你审完再提交）。
• 分支两档：简化档（个人小工程）单分支 main + 频繁小 commit，跑偏就 reset；严谨档（改动大）每任务一个 feat/xxxx 分支，review 通过再合 main。
• 让 AI 配合：commit message 让 AI 生成 conventional commit（feat/fix/refactor/test/docs/chore）；pre-commit hook 跑 lint/typecheck；大改动前先 commit 一个干净 checkpoint。
• 红线：.gitignore 第一天配好（node_modules/.env/build）；敏感信息不进 git；别让 AI force push / 改写共享历史 / 删远程分支。

口诀：工作区干净再开工，一卡一 commit，测试绿才提交，人审 diff 当扳机，跑偏就 reset，垃圾密钥进 ignore。

七、完整生命周期流程

阶段切换：收尾旧阶段 → 定义新阶段

一个阶段的任务都做完后，按三步推进：

1. 收尾旧阶段：归档完成卡（archive/vX.Y/）→ 补 ADR → 提炼规则进 CLAUDE.md → 更新 CHANGELOG。
2. 定义新阶段：先写清「什么算成功」。功能阶段验收是「能用」；优化阶段验收必须是「指标」（如 P95 < 200ms、重复代码 -30%、覆盖率 40%→70%）——没有指标的优化 = 玄学。
3. 拆卡开新循环：从新目标拆任务卡（编号接着走、阶段字段更新），/clear 开新会话，照常「一卡一 commit 一验证」。

优化阶段额外三防：动手前固化基线（测一遍 + commit）防改坏；每卡可量化验收防没止境；大重构先 plan mode 防跑偏。

口诀：旧阶段归档干净，新阶段先定指标，再拆卡开新会话。

一句话收束：目录上把「地图」和「规则」分开，上下文上分层精简常维护，记录上流水归工具结论归文件，提问上把约束写成命令和句式，任务上拆到「一卡一 commit 一验证」——这就是把 vibe coding 从「玄学」变成「工程」的全部。

相关

• new-project-scaffold —— 配套的脚手架命令，把 §一 的目录骨架一键初始化。
• Claude Code使用技巧 —— 命令、快捷键与机制的速查手册，与本文互补。

来源

• Steering Claude Code: skills, hooks, subagents and more（Anthropic 官方）
• vibe-coding-rules: 54 production architecture rules（CLAUDE.md / cursor rules / skills 实例）
• Beyond Vibe Coding: Best Practices in 2026（Vonage）
• Architecture Decision Records（ADR 概念来源）