Appearance
端到端 Walkthrough：从需求到 PR
这是全书的收官串讲：用一个功能，把六大范式 + 落地构件 + 安全闸门走成一条可复制的动线。每一步都标明"产出什么、对应哪章"。
场景设定
需求：给一个 Web 服务新增"导出用户报表为 CSV"功能。要求处理大数据量、含个人信息（PII），要进生产。
这个场景同时踩中：意图不清（边界）、正确性（分页/编码）、安全（PII 泄露、注入）、存量（要接现有鉴权）。正好把全流程走一遍。
全流程时间线
text
① 澄清意图 → ② 写规格 → ③ 规格里入库 → ④ 先写测试 → ⑤ 拆解任务
→ ⑥ AI 实现 → ⑦ 验证闸门 → ⑧ 自查安全 → ⑨ code review → ⑩ 开 PR / 归档① 澄清意图（Vibe 一下就好）
先跟 AI 对话式把问题问全，不写生产代码（Vibe Coding）：
- 数据量多大？要不要异步导出 / 分页？
- CSV 里含哪些字段？哪些是 PII，要不要脱敏？
- 谁能导出？鉴权沿用现有哪套？
② 写规格（切到 SDD）
把结论沉淀成结构化 spec，只钉最容易返工的决定（SDD）：
markdown
## 目标
导出用户报表为 CSV，最多 10 万行，超量走异步任务。
## 边界
- 影响：report 服务、鉴权中间件、导出任务队列。
- 不做：XLSX、定时订阅导出。
## 验收标准
- 含 PII 列默认脱敏，非授权角色不可导出明文；
- 字段含逗号/引号/换行 → 正确转义；
- 超 10 万行 → 返回任务 ID，轮询取下载链接。
## 异常
- 空结果导出含表头的空文件；无权限 → 403 且不泄露字段。③ 规格入库（OpenSpec / Spec Kit）
棕地 + 涉鉴权，用 OpenSpec 的"提案→审查→隔离生成"把 spec、design、tasks 落进仓库，变更可审计。产出：
proposal.md（为什么）、design.md（怎么做，含"必须复用现有鉴权中间件"）、tasks.md、spec delta
④ 先写测试（TDD）
把验收标准逐条翻译成测试（TDD）：
python
# 环境：终端，Python 3
# test_export.py（节选，先写，此时实现不存在 → Red）
def test_pii_masked_for_non_admin():
csv = export_report(user=VIEWER)
assert "****" in csv and real_phone not in csv
def test_csv_escapes_comma_and_newline():
row = escape_cell('a,"b"\nc')
assert row == '"a,""b""\nc"'
def test_over_limit_returns_task_id():
resp = export_report(user=ADMIN, total=200_000)
assert resp["task_id"] and resp["status"] == "queued"⑤ 拆解任务（writing-plans）
按 superpowers 流程：把 tasks.md 拆成小步——转义工具 → 查询分页 → 鉴权挂钩 → 异步任务 → 接口。每步都能独立验证。
⑥ AI 实现（喂对上下文）
用上下文工程只把相关文件 + 规格喂给代理（别灌整仓），逐任务实现。注意识别 AI 幻觉：CSV 转义/鉴权 API 要核对是否真实存在。
⑦ 验证闸门（Harness）
每轮改完调用执行工装的最小闸门脚本，机器判定"过没过"：
text
[harness] running lint: ...
[harness] running test: python -m pytest -q
[harness] all checks passed ← 才允许进入下一步若测试失败，禁止 AI 改断言凑绿（组合实战·坑1），只能改实现。
⑧ 安全自查（对照清单）
按安全清单过一遍这个场景的高危点：
- [ ] PII 是否默认脱敏、越权是否返回 403 而非字段泄露？
- [ ] CSV 注入（单元格以
=/+/-/@开头会被电子表格当公式执行）是否防护？ - [ ] 依赖包名是否为真实存在（防 slopsquatting）？
- [ ] 大文件导出是否有 DoS 风险（限流 / 异步）？
⚠️ 特别提示：**CSV 注入（Formula Injection）**是"导出"功能最经典的坑——只转义逗号引号还不够，对以公式字符开头的单元格要额外加前缀单引号。
⑨ Code Review（人做终审）
评审重点从"语法对不对"转向"是否满足 spec 与边界"（团队治理）。谁 merge 谁负责，AI 不是免责理由。
⑩ 开 PR / 归档
通过闸门与评审后开 PR；OpenSpec 场景用 archive 把这次 spec delta 合并进主规格，让仓库始终是事实来源（Harness 关键点 2）。
每步对应关系一览
| 步 | 动作 | 产出 | 对应章 |
|---|---|---|---|
| ① | 澄清意图 | 问题清单 | 03 Vibe |
| ②③ | 写规格并入库 | spec / proposal / design / tasks | 05 SDD |
| ④ | 先写测试 | test_*.py | 04 TDD |
| ⑤⑥ | 拆任务 + 实现 | plan / 代码 | 06 工作流 · 07 上下文 |
| ⑦ | 验证闸门 | 通过信号 | 08 Harness |
| ⑧ | 安全自查 | 打勾清单 | 15 安全 · 16 幻觉 |
| ⑨⑩ | 评审 + PR/归档 | PR / 更新后的 spec | 18 治理 |
本章小结
- 一条完整动线：澄清 → 规格 → 入库 → 测试 → 拆解 → 实现 → 闸门 → 安全 → 评审 → PR。
- 每一步都不是新发明，而是前面某一章的落地；卡住时回到选型决策树定位该用哪层。