Engineering Docs

让功能设计长期收敛在同一 feature，任务围绕设计执行，结果由可重复运行的 harness 验证。阅读优先，不通过堆文档和固定模板制造流程。

先确认已有约束

读取项目 AGENTS.md、文档索引、相关设计和实际代码。保留现有规则、用户修改与链接；只补任务需要的部分。不要把参考项目的语言、框架、核心分层或产品功能变成新项目要求。

初始化时按下列结构建立必要入口；维护时先找到原 feature。仅结构示意中的文件有实际用途时才创建，不能为每个目录批量生成占位文档。

AGENTS.md
README.md                       # 暴露工程文档入口
.agents/docs/
  README.md                     # 总索引
  architecture-YYYY-MM-DD.md               # 长期架构与依赖边界
  milestones-YYYY-MM-DD.md                 # 阶段总览
  milestones/
    1-<name>-YYYY-MM-DD.md                 # 每阶段独立管理多个 feature
    2-<name>-YYYY-MM-DD.md
    3-<name>-YYYY-MM-DD.md
  ui-guidelines-YYYY-MM-DD.md              # 用户界面共同约束
  harness-YYYY-MM-DD.md                    # 可执行验证与证据规则
  feature-<name>-YYYY-MM-DD.md
  plan-<task>-YYYY-MM-DD.md                 # 按需
  refctory-<task>-YYYY-MM-DD.md             # 按需，保留团队命名
  bugfix-<task>-YYYY-MM-DD.md               # 按需
  research/
    <topic>-YYYY-MM-DD.md
  archive/

1、2、3 表示递增阶段编号，不要求项目必须有三个阶段。工程初始化不列作里程碑 0。维护已有项目时先确认迁移范围，不擅自批量重命名；采用本规范后迁移旧文件并修复全部引用，不能破坏已有入口。

文档各司其职

• architecture：整体职责与依赖方向，跨特性共同边界；不复制具体 API 或阶段任务。
• milestones：总览只维护阶段导航、依赖和状态。独立阶段文件说明本阶段一句话需求、交付结果、feature 列表、依赖、状态、验收证据和退出条件。一个 feature 可跨阶段持续扩展，链接始终指向原文件。
• feature：以功能特性为单位的长期技术设计。开头优先用一句话讲清“谁在什么场景，需要什么结果，为了解决什么问题”，随后明确目标、非目标与前置条件；这些内容属于 feature，plan 只引用，不另行定义。余下内容按阅读需要自然组织，不固定章节、顺序和表格。
• plan：只包含计划、任务列表、验证和涉及的 features，用于执行具体任务或组织一次 MVP 交付。计划说明范围与顺序，任务列表记录任务间的先后依赖、完成判据和状态，验证引用 feature 的场景并记录实际结果，features 列表链接本次涉及的特性。plan 不另设目标或前置条件，也不写 Expose、接口、数据结构、架构设计或执行约定，也不暂存待提炼的技术方案。整体 MVP 按稳定能力边界派生 feature，将技术内容直接放入 feature，plan 仅保留任务与引用；不按每个模块或步骤机械拆分。小任务直接写入已有 feature，不必新建 plan。
• refctory：重构既有设计。说明为何扩展不足、保留的不变量、职责调整、兼容或迁移，以及前后 harness。默认就地写入 feature；复杂且需独立评审时才拆文件，完成后把当前设计回填 feature。
• bugfix：复现、根因、最小修复和修复前后回归；小修复就地记录，需要独立追踪才拆文件。
• research：保存有独立保留价值的调查、版本、来源、事实与假设、比较和未验证项。短调研就地记录；采纳结论回填 feature，调研不能自动成为批准的设计。
• archive：已完成任务或退役、被替代的设计。仍有效的 feature 不因一次任务完成而归档，保留日期、原因、替代链接和证据，修复所有引用。

所有具体工程文档都使用首次创建日期后缀 -YYYY-MM-DD.md，包括架构、里程碑总览与独立阶段、UI 指导、harness、feature、plan、refctory、bugfix 和独立 research，例如 feature-agent-messages-2026-10-29.md、plan-cli-mvp-2026-10-29.md。日期必须是有效日历日期；后续维护保留原名与日期，更新日期写正文，不按任务、更新日期或版本复制 feature。AGENTS.md、各级 README.md 和通用模板保留稳定入口名称，不加日期。

最小面、稳定契约与公开入口

先复用已有 feature、接口和扩展点。设计对修改封闭、对扩展开放：保持已批准职责、契约和不变量稳定，通过插件或可选能力扩展；不禁止修正文档事实，也不允许以此为由保留已确认缺陷。

设计要讲清实际代码依据、最小修改范围、模块和数据归属、执行顺序、相关失败与清理。公开面（Expose）说明调用方、输入输出、错误、生命周期及兼容性，提供最小调用示例；无新增接口时一句话说明即可，不强制 Expose 独立章节。没有真实调用方就不新增公开 API，不为假设需求引入通用框架。

范围或既有契约必须变化时，在原 feature 明确 refctory 决策与迁移，不能静默改写承诺。实现后合并当前技术说明，任务流水放在 plan 或精简记录中。

引用与用户界面

根 README 链接工程索引，所有有效文档从索引可发现。每份文档链接上级索引、依据和相关材料；feature 与独立任务双向链接。实现和 harness 存在后链接实际文件；未创建时明确注明，不能放假链接。

公开暴露文档是提供可发现的仓库入口，不是替用户发布外网网站或开放私有仓库。文档不含凭据、客户数据和本机绝对路径。

所有用户界面相关 feature、plan、refctory、bugfix、research 与验收记录必须直接链接项目实际的带日期 UI 指导文件（例如 ui-guidelines-2026-10-29.md），并说明相关交互及验证，不能只间接引用总索引。指导文件覆盖用户任务、输入保留、状态反馈、错误与取消、焦点、键盘、可访问性及适用的窗口尺寸；不臆造品牌视觉或技术栈。纯后端工作不强制引用。

Harness 与工程流程

每个 feature 都要有可执行验证设计：从真实公开入口输入，观察结果并客观判断目标是否达成。说明确定性依赖或替身边界、相关故障、有限超时、退出码、资源清理和证据。简单变更复用已有 harness，不强制另建框架或测试包。

循环为“运行 → 对照目标与证据 → 修正 → 重跑失败及受影响场景”。不能删断言、吞错、无界重试或放宽时间掩盖失败。离线通过不证明真实集成通过，截图不能单独证明交互正确。未运行、未实现、未验收分别标明。

建立或调整开发流程时，读取 流程细则。已有项目规则与用户授权优先；流程初始化本身不需要创建递归的 feature、plan 和审批文档。

检查与交付

检查文档之间的语义一致、最小范围、界面引用与验收覆盖，再执行：

python <skill-dir>/scripts/check_docs.py --root <project-root>

Python 3.9+ 标准库即可。脚本只读检查本地行内链接、标题锚点、根入口可达性、具体工程文档日期命名（README 与模板除外），以及 plan 中明显的技术设计章节；不要求固定标题，不判断设计质量或任意文字是否涉及 UI，不验证远端页面。命令中的路径替换为实际目录，python3 也可使用。

交付说明变更入口、实际检查和未验证项。只有任务明确授权时才提交、推送、创建 PR 或发布；引用一个仓库或要求文档公开可发现不自动授权部署、合并、安装 Skill 或修改成员环境。