code-as-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# 代码即核心业务文档

**代码、日志和必要的就近注释共同构成核心业务信息。** 已实现的业务流程、规则、状态流转和约束以代码、SQL、schema、配置和测试为准；注释只补充代码无法直接表达的业务语义。日志不得包含敏感数据。

## 持久业务文档的最小边界

持久业务文档只保留代码、测试和少量就近注释仍无法充分表达的关键业务信息，例如跨多个模块的总体规则、边界或协作关系。文档应精简地说明这些不可由代码直接还原的信息，并指向相关代码；不要复述字段、调用顺序或局部实现规则。

如果一篇文档只剩业务概念或流程到代码入口的引用、没有独立业务价值，则不保留它。项目没有文档体系时，不要为记录业务信息新建持久文档目录、模板或治理体系；直接让代码和必要的就近注释承载信息。

稳定项目约定、面向外部读者的使用说明、集成协议、运维手册或合规记录按其用途保留，不把它们误当成内部业务文档清理。

## 开发后独立 review 的临时需求文档

仅当 `skill:align` 的对齐推进交互已确认**需要开发后独立 review**时，在开发前建立一份该次 review 专用的独立需求文档；不因任务规模、是否全新或是否已有需求文档自动创建。默认的开工前方案审核直接使用当前合同与方案，不触发本文档。选择不需要开发后 review 时不创建该文档，也不安排开发后 review；前审按 `skill:align` 的约定执行。

把文档放在运行环境约定的临时目录，不放入项目文档体系，不提交、不发布，也不转成持久 spec。即使已有需求文档，也要为已选择的独立 review 单独创建此文件；可以以已有文档为事实来源，但不修改或替代它。

文档采用接近验收文档的结构，写清：需求目标、范围与非目标、前置条件或关键约束，以及可逐项核对的验收项（场景、预期结果，必要时包含边界和失败结果）。只记录 review 判断需求符合性所需内容；不记录实现方案、字段清单、调用顺序或开发过程。

分批实施时保留整体目标及其验收项，标明本批覆盖与剩余项；批次安排本身不改变验收标准。

该文档仅作为 review 的验收输入，不替代开发执行合同。用户明确调整目标、范围、关键约束或验收标准时，在实现调整前直接更新相应条目：同一事项仅保留当前有效要求，取消项及其引用一并移除。实现者的技术解释、测试失败和调试发现不能自行改变验收标准。

开发完成后，调用方把当前验收文档与明确的目标 diff 显式交给 reviewer；reviewer 不自行扫描临时目录。单次 review 返回不等于任务关闭：文档保留到本次 findings 已处置且已授权复核结束，期间可作为同次复核的验收输入，不因此自动授权修复或复审。

本次任务关闭后弃置文档。之后的新需求与普通增量只依据当次请求、当前代码、测试及有价值的持久文档推进，不扫描或沿用已关闭任务的临时验收输入。

## 项目规则的极简承载

已有位置能承载就补在那里，不为一条规则新建治理体系，也不默认多层重复：

- 需要 Agent 高频遵守的稳定项目约定放 `CLAUDE.md` / `AGENTS.md`；
- 无法由代码表达且需要持续保留的跨模块决定或业务关系放现有 spec / 项目文档；
- 可稳定机械判断的约束交给 test、lint、type 或 CI；
- 必须在特定生命周期自动发生或即时反馈的动作才用 hook。

一个规则可以有说明层和执行层，但每层都应提供独立价值。

## 处理现有业务文档

先确认是只读检查还是已授权维护；只读请求只返回判断与建议。获得修改授权后：

- 删掉或收敛代码能够还原的字段、调用流程和局部规则；
- 只剩代码入口引用且没有独立业务信息的文档不保留；
- 文档中的局部业务 why 下沉到相邻代码注释；
- 保留代码无法充分表达、且需要跨开发周期维护的关键跨模块业务信息；
- 删除可能损失无法恢复的业务知识时，先指出疑点，不凭猜测迁移。

不要以整理业务知识为由扩大到无关重构，也不要把面向外部读者的交付文档误删成内部业务文档。

From cheng6563/litepowers, MIT.

More from cheng6563/litepowers