vibe-coding-kit AGENTS.md

vibe-coding-kit 治理宪法 (Governance Constitution)

这是 vibe-coding-kit 的最高治理文件。Codex 在每次对话开始时自动加载它。 在其他平台（ChatGPT、Codex）使用时，将本文件内容复制为 system prompt 前缀。 所有规则派生自 harness.json——那是唯一真实来源。

---

一、最高原则

1. 复杂度是负债，不是资产。 每多一个组件、一个依赖，都是向未来借债。
2. 需求没说清，等于没说。 AI 会朝着模糊的方向飞速跑偏。
3. 先说问题，再说方案。 描述方案会锁死 AI，描述问题才有更优解。
4. 没有代价的方案不存在。 不讲代价的推荐不可信。
5. 维护成本是最终裁决。 一年后修不修得动，比什么都重要。

---

二、语言与格式

• 正文：简体中文
• 代码注释：简体中文
• 变量名/函数名：英文，见名知意
• 文件编码：UTF-8
• 行尾：LF

---

三、文件命名强制规范

产出物	路径	模板
PRD 文档	docs/prd.md	examples/PRD-模板.md
项目说明书	docs/项目说明书.md	examples/项目说明书-模板.md
开发文档	docs/开发文档.md	examples/开发文档-模板.md
进度账本	docs/进度账本.md	examples/进度账本-模板.md
项目进度卡总表	.dsu/progress/index.md	examples/项目进度卡-总表模板.md
模块进度卡	.dsu/progress/modules/duXX-xxx.md	examples/项目进度卡-模块模板.md
任务 Closeout 卡	.dsu/progress/tasks/任务ID.md	examples/项目进度卡-任务模板.md

• 所有产出物写入 docs/ 目录。如 docs/ 不存在，先创建它。
• 不得使用其他文件名或路径。
• 项目进度卡是开发期上下文索引，固定写入 .dsu/progress/，不写入 docs/。

---

四、必须产出的章节（不可跳过）

PRD（docs/prd.md）至少包含：

• 1. 文档元信息（文档状态、版本、产品名称三项不可为空）
• 1. 产品结论（含核心定位 + 明确不做）
• 1. 用户、场景与形态（含"它活在哪"的明确决定）
• 1. 验收标准（每条具体可验证，不能是"系统正常"这种空话）
• 1. MVP 完成定义
• 1. 以后再说

项目说明书（docs/项目说明书.md）至少包含：

• 一句话
• 需求基准描述
• 产品思考模块（预留）
• 选定技术栈
• 验收清单
• 以后再说清单
• 决策复盘 / 案例库

开发文档（docs/开发文档.md）至少包含：

• 1. 文档元信息（文档状态、版本、产品名称三项不可为空）
• 1. 概述（含本期范围 + 本期不做）
• 1. 总体架构
• 1. 端到端流程
• 1. 模块清单
• 1. 目录结构
• 1. 数据结构与存储
• 1. 接口约定
• 1. 核心算法 / 业务规则
• 1. 分阶段里程碑
• 1. 开发任务总表
• 1. 测试计划
• 1. 反馈回路

---

五、流程纪律（按门推进）★

派生自 harness.json 的 workflow 块。这是为了解决"AI 不按步骤推进、乱序跳步"而设的硬规矩。

1. 以账本为状态来源。 docs/进度账本.md 是流程的唯一状态来源。每轮对话开场先读它，向用户报"当前在哪个阶段、第几步"；不存在就照模板创建。
2. 按门推进。 流程是 S1 需求 → S2 选型 → S3 上线 的有序流水线。每个阶段有出口门（exit_gate），每一步有退出条件。一步的退出条件没满足，不进下一步；上一阶段出口门没过，不进下一阶段。
3. 每过一步回写账本。 做完一步立刻更新账本（标状态、推进当前步骤）。
4. 跳步要留痕。 只有分诊判定为"轻"（自己用 / 一次性 / demo）时，才允许跳 required:false 的步骤，且必须在账本"跳步留痕"写一行理由。required:true 的步骤一律不准跳。
5. 轻重两种模式。 轻模式可"几步合并、一次报门"，但出口门无论轻重都要过——省的是停顿次数，不是产出质量。
6. 红线优先。 涉及"动钱 / 动别人隐私"时，survival 的红线提示优先级高于"按门推进"——先停下来提醒找真人。
7. 问题解决后沉淀案例。 遇到需求矛盾、缺决策、实现卡住、技术方案偏离预期时，先暂停处理；本次解决后，必须把"问题是什么、有哪些选项、最终怎么决定、下次怎么复用"写入 docs/项目说明书.md 的「决策复盘 / 案例库」。