GitZhiQing zero-coding：从零到稳定开发
从零开始开发一个项目：先让想法自由落地，再固化为范围契约，然后搭起可运行的骨架，进入稳定迭代。
核心信念：Agent 能力越强，过多的文档越是束缚。只维护代码与 git 历史推导不出的信息，保持最小必要。
一条判断标准：能从代码 + git 历史推导的 → 不写；表达意图、范围、约束、决策的 → 写。
产物快照原则
所有产物——代码、注释、文档、提交说明——是零历史的纯状态快照：按“从一开始就是这样”书写，演进过程交给 git 与 DECISIONS。
唯一判据是新读者测试：一年后首次打开文件、从未参与本对话的人，读到的每个字仍须成立。
- 注释只写代码表达不了的 why（非显然约束、故意偏离、坑、workaround）；禁止复述代码，禁止“修复了 X”“改为 Y”“不再使用”这类变更叙事。
- SPEC 与 README 用现在时描述当前状态；需求变更 = 重拍快照，按“新需求从一开始就是这样”重写，不追加变更说明。
- commit message 写 what 与 why，这是变更历史的唯一归宿；PR 描述合并后的最终状态，像首次提出该变更一样。
- ZERO 与 DECISIONS 是刻意保留的历史账本，不受本原则约束。
- 输出前自检：产物中出现“之前”“原来”“已移除”“不再”“removed”“instead of”等历史引用即视为缺陷——清除，或降级为一条 commit message。
文档集（共 5 个，不增不减）
| 文件 | 读者 | 一句话定位 | 生命周期 |
|---|---|---|---|
| docs/ZERO.md | 自己 | 自由灵感本，格式零约束 | SPEC 确认后降级为档案 |
| docs/SPEC.md | 用户 + Agent | 灵感的固化，范围契约 | MVP 交付后并入 README 并删除 |
| docs/DECISIONS.md | Agent | 轻量 ADR | 永久，只追加 |
| AGENTS.md | Agent | 会话级上下文 | 持续维护，保持克制 |
| README.md | 人类 | 是什么、怎么跑 | 收尾时完善 |
docs/ZERO.md — 灵感
最初期的灵感本，完全自由：
- 谁写都行：开发者本人随时手写；用户口述、Agent 代为追加亦可。
- 写什么都行：一时灵感、调研资料、参考链接、半成品想法、相互矛盾的猜测，都值得留。
- 格式零约束：一句话、长段落、清单、随手粘贴皆可；不要求日期或标题，无需前后一致。
不修正、不总结、不评判——允许争议、不确定与错误的存在，这正是它的价值。
Agent 对此文件的职责是读和理解，不是整理：除非用户要求，不重构、不改写。与 SPEC 冲突时，以 SPEC 为准。
docs/SPEC.md — 固化
经 Phase 1 结构化访谈固化，是“从灵感开始”阶段最重要的文档。必含四节：
# SPEC
## 问题 （解决什么问题、为谁）
## MVP 范围
## Non-goals （明确不做什么）
- 未获用户明确确认前，不写任何产品代码。
- 范围变更 = 重拍快照：按“新需求从一开始就是这样”重写，不追加变更说明——SPEC 是除 ZERO 外文档集中唯一可改写的文件。
docs/DECISIONS.md — 决策
轻量 ADR，只追加，不修改。条目一行式：
D1 · 2026-09-13 · 存储用 SQLite · 为什么：单机自用，零运维优先于扩展性
- 决策被推翻时，追加新条目并注明“取代 D1”，不删旧条目。
- 重构或选型前必读；与生效条目冲突时，先向用户提出，不擅自更改。
AGENTS.md — Agent 上下文
每次会话都注入，必须克制（目标 <100 行）：构建 / 测试 / lint 命令、目录速览、硬约束、指向其他文档的链接。
它是唯一持续维护的文档，但只在 Agent 犯重复错误时，才把纠正追加进来。
README.md — 门面
给人看（包括未来的自己）：是什么、为什么、怎么跑起来。一屏以内；骨架期写最小版，收尾期完善。
工作流
Phase 0 · 捕获
触发：用户描述一个新想法，或已自行写好 docs/ZERO.md。
开局说明（仅首次进入工作流时）：用 3~5 句话向用户交代全程——四个阶段（捕获 → 固化 → 骨架 → 稳定开发）怎么走、五个文档各自的角色、两道硬门槛（SPEC 未获确认不写产品代码、决策由用户拍板）。与捕获动作同轮呈现，不单独占用一轮；后续会话不再重复，细节到各阶段再展开。
- ZERO.md 已存在 → 通读理解，不整理、不修改。
- 用户口述想法 → 原话追加进 ZERO.md，空行分隔即可，不加格式包装。
- 可自由讨论，但不做技术判断，不创建其他项目文件。
完成：用户明确表示“开始规划”。
Phase 1 · 固化
触发：ZERO.md 存在且用户决定立项。 机制：结构化访谈——逐轮逼近，直到与用户达成共享理解。
怎么问
把待定决策建模为设计树：每个决策分支出依赖它的决策。
前沿 = 前提已定的那些决策，即此刻无需猜测就能问的问题。
每轮一次性问完整条前沿：逐条编号并附推荐答案，等用户回答后再进下一轮：
❓ Q1 - <标题>：<问题正文，可含选项> ➡️ 推荐：<答案 + 一句理由>
回答重塑树：已定决策把前沿向外推、解锁下游问题；依赖本轮未决项的问题，留给后续轮次。
什么不问
- 事实自己查：环境、工具、资料等凡能自行调研的，绝不问用户（必要时派子 Agent）。调研未返回视同未定前提——只阻塞它的下游，其余前沿照常推进。
- 决策留给用户：Agent 只推荐、不拍板；每项决策都摆给用户并等待。
何时结束
前沿为空：设计树每个分支都已访问，没有任何决策被默默假设。把全部已定决策整理为 SPEC 草案交用户确认——确认即本阶段完成。
Phase 2 · 骨架
- 初始化代码骨架，达到“可运行空壳”（hello-world 级）。
- 写 AGENTS.md——每条命令必须真实执行过。
- README 写最小版（怎么跑）。
- DECISIONS.md 逐条记录本阶段全部选型。
- 有环境变量则加 .env.example。
完成：AGENTS.md 中每条命令验证可执行。
Phase 3 · 稳定开发
迭代循环：按 SPEC 开发顺序取下一块 → 实现 → 测试绿 → 提交。
文档纪律：
- 不可逆选型拍板 → 当场追加 DECISIONS（Agent 起草，用户只确认理由）。
- Agent 犯重复错误 → 纠正写入 AGENTS.md。
- 范围变化 → 修订 SPEC；若是永久放弃，同时记一条 Decision。
- ZERO.md 降级为档案，不再影响开发决策；新想法走 SPEC 修订。
收尾（MVP 交付）
- SPEC 收缩为一节并入 README，然后删除。
- README 完善至“一屏”标准。
- ZERO.md 保留为历史档案（或按用户意愿删除）。
- DECISIONS 与 AGENTS 继续服役，进入下一个循环。
冲突裁决
- 代码与文档冲突 → 以 DECISIONS.md 为准，并提醒用户。
- 文档间冲突 → SPEC（范围）> DECISIONS（约束）> ZERO（仅历史）。
- 用户当面指示 > 一切文档。