HWLAB 文档治理与 docs-spec 入库规则

本文是 HWLAB 仓库内固化的 docs-spec 规则副本和可执行摘要，也是本仓库唯一维护 docs-spec 使用规则的长期参考。编辑 AGENTS.md、docs/reference/*.md 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 docs-spec skill，也要以本文作为 HWLAB 本地权威落点。

中文优先规则只在 chinese-first-documentation.md 维护，用户和参谋反馈分流规则只在 user-feedback-triage.md 维护。本文只交叉引用这些规则，不替代 commander-collaboration.md 中由 pikasTech/HWLAB#131 固化的一手事实和真实推进边界。

AGENTS.md 规则

AGENTS.md 只作为项目级顶级索引，用于快速定位命令、入口和长期参考文档。
与 AGENTS.md 同等作用的文档，例如 CLAUDE.md，只保留 @AGENTS.md 引导，避免多套口径漂移。
每个命令在 AGENTS.md 中只保留一条主索引；参数、背景、判定标准写入链接的 reference 文档。
每个列表项只描述一个功能点，用一句中文概括，不在顶层展开实现细节。
AGENTS.md 必须索引中文优先、用户反馈分流、PR 工作流、#78 上位约束和 docs/reference/ 入口。

docs/reference 长期参考规则

docs/reference/ 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准。
不写日期化日报、一次性过程记录、实测流水账、容易过时的 changelog 或临时 blocked 记录。
每个功能点优先对应 docs/reference/ 下的独立 Markdown 文档；AGENTS.md 只链接和摘要。
功能需要补充说明时，先更新 reference 详细文档，再更新 AGENTS.md 的一句话摘要。
知识更新遵循：增加新稳定知识、删除过时知识、修正错误知识、合并重复知识。
跨文档重复时，选择一个 reference 作为唯一权威出处，其他文档交叉引用它。
涉及 skill 的 reference 必须说明该 skill 与 HWLAB 代码、硬件、目录和验收标准的关系；通用 CLI 用法直接引用 skill，不在仓库内复制成另一份通用手册。

过程文档蒸馏规则

过程文档是历史资料，通常带时间戳，时效性强，不能直接进入长期参考。
蒸馏只提取稳定结论、边界、验收标准和禁止事项。
不篡改过程文档；过程记录是原始来源。
大文件按滑动窗口阅读，读一段就提炼稳定结论，不等全部读完才更新 reference。
新稳定结论覆盖旧冲突结论；旧过程只作为历史来源。
可以简述重要发展脉络，但不能把长期参考写成流水账。

中文和反馈治理

中文优先规则见 chinese-first-documentation.md；长期参考必须中文主导。
用户和参谋反馈分流规则见 user-feedback-triage.md；默认按高优先级用户反馈处理并挂到 #7。
影响 M3 判定的文档必须显式对齐 DC-DCSN-P0-2026-003 / #78，不得把 SOURCE、LOCAL、DRY-RUN、fixture、edge-only health 或前端状态写成 M3 DEV-LIVE。
影响发布、运行态、端口和 PR 流程的规则必须交叉引用对应 reference，不在多个文档里各写一套。

本地入库和同步机制

本文保留外部 docs-spec 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理。
每次任务涉及 AGENTS.md、docs/reference/*.md 或过程文档蒸馏时，runner 应先读取外部 docs-spec skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。
如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。
docs/reference/README.md 是长期参考入口；新增 reference 后必须更新该索引和 AGENTS.md。

HWLAB 当前应用

#7 是指挥官看板和用户反馈集中入口。
#78 / DC-DCSN-P0-2026-003 是 M3 虚拟硬件可信闭环上位约束。
#121 要求 issue 和长期文档中文化。
#122 要求用户和参谋反馈默认高优先级并挂到 #7。
#123 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill。
当前 HWLAB 的 16666/16667、D601 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护。

docs-spec 原文副本

以下副本来自当前 runner 可见的 docs-spec skill，用于满足 #123 的本地固化要求。后续如果外部 skill 更新，应按“本地入库和同步机制”同步。

---
name: docs-spec
description: 用于指导 docs 的文档规范，编辑 CLAUDE.md/AGENTS.md 或者 docs/reference/*.md 或者进行过程文档蒸馏时必须加载本 SKILL
---

- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和文档。
    - 其他和 `AGENTS.md` 具有同等作用的文档（例如 CLAUDE.md )中只写入一行 `@AGENTS.md` 将其引导到 `AGENTS.md`，避免多种口径互相不一致。
    - 每个命令在 `AGENTS.md` 中保留一条主索引，命令下面可以挂多个功能子列表。
    - 每个子列表只描述一个功能点，并使用一句话概括，不在此处展开实现细节、参数说明或背景分析。
- docs/reference 长期参考文档
    - `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准；不要写日期、一次性过程记录、实测流水账或容易过时的 changelog 式内容。
    - 每个子列表应独立对应一个 `docs/reference/` 下的参考文档；如果同一命令包含多个功能，则分别链接到各自文档。
    - 所有功能的详细说明统一写入 `docs/reference/` 下的独立 Markdown 文档，并在 `AGENTS.md` 中提供对应链接索引。
    - 当某项功能需要补充说明时，优先更新 `docs/reference/` 的详细文档，再回到 `AGENTS.md` 维护对应子列表的一句话摘要与链接。
    - 知识更新原则 - 增加新知识、删除过时知识、修改错误知识、合并重复知识
        - 避免重复 - 对于同文档重复的内容应当进行合并，对于跨文档重复的内容，应当选择或者新建一个文档作为唯一权威出处，其他文档交叉引用权威出处。
    - `docs/reference/` 中涉及 skill 的文档，必须突出该 skill 与当前项目代码、硬件、目录和判定标准的具体联系；通用安装、CLI 参数、子命令和完整用法直接交叉引用对应 skill 的 `SKILL.md`，不要在 reference 中重复抄写一份通用说明。
- 过程文档蒸馏
  - 过程文档指的是开发过程中的过程记录，通常带有时间戳，特征是时效性明显，容易过时，代表了系统的发展和转变过程。
  - 过程文档蒸馏指的是将过程文档蒸馏为长期参考文档。
  - 蒸馏原则
    - 从旧到新原则 - 先从旧的过程文档开始整理，然后逐渐处理新的。
      - 滑动窗口 - 对于大的过程文档文件，采用滑动窗口策略，读一定长度（例如 500 行）就更新一次长期参考文档，不要全部读完再更新。
    - 新的覆盖旧的 - 新的过程文档有更高的重要性，在新的和旧不一致时，应当以新的替换旧的。
    - 简述发展过程 - 在长期参考文档中用简短的篇幅描述总体的发展过程 OUTLINE。
      - 避免将发展过程写成流水账。
      - 越早期的发展过程越简略地写。
      - 重要的发展过程节点可以交叉引用过程文档。
  - 不要篡改过程文档 - 过程文档是一手的历史资料，禁止对过程文档进行篡改。

7.9 KiB Raw Blame History