# Zero Coding

> 从零启动一个个人项目并维持稳定开发工作流：维护最小文档集（ZERO / SPEC / DECISIONS / AGENTS / README），按“捕获 → 固化 → 骨架 → 稳定开发”推进。 当用户带着新想法从空目录开始（“我想做个……”）、需要固化需求、搭建项目骨架 或防止文档膨胀时使用。 当项目已有成熟的文档体系与开发规范、或用户只是临时求助并不打算立项时， 不要使用本 skill。

- Skill: `gitzhiqing/zero-coding` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gitzhiqing/zero-coding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitzhiqing/zero-coding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: GitZhiQing (https://skillmd.com/u/gitzhiqing)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gitzhiqing/zero-coding

---


# 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 · 骨架

1. 初始化代码骨架，达到“可运行空壳”（hello-world 级）。
2. 写 AGENTS.md——每条命令必须真实执行过。
3. README 写最小版（怎么跑）。
4. DECISIONS.md 逐条记录本阶段全部选型。
5. 有环境变量则加 .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（仅历史）。
- 用户当面指示 > 一切文档。