HWLAB Documentation Governance

This is the local HWLAB copy of the docs-spec rules. Use it when editing AGENTS.md, docs/reference/*.md, or distilling process records into stable reference material.

AGENTS.md

AGENTS.md is only the project-level top index for quickly locating commands, entry points, and documents.
Documents with the same role as AGENTS.md, for example CLAUDE.md, should contain only @AGENTS.md so multiple top-level mouths do not drift.
Each command in AGENTS.md keeps one main index entry; command details live in the linked reference document.
Each sublist item describes one function point in one sentence. Do not expand implementation details, parameters, or background analysis there.

docs/reference

docs/reference/ records only stable, reusable entry points, prerequisites, constraints, and decision criteria.
Do not put one-time logs, timestamped execution records, changelog-style history, or easily stale status notes in docs/reference/.
Each feature or command detail should have an independent reference document under docs/reference/; AGENTS.md links to it.
When a feature needs detail, update the detailed reference first, then update AGENTS.md with a one-sentence summary and link.
Knowledge updates follow these rules: add new stable knowledge, delete stale knowledge, fix wrong knowledge, and merge duplicates.
Avoid duplicated authority. If content repeats across documents, choose one reference as the authority and point other documents to it.
If a reference mentions a skill, explain how the skill relates to HWLAB code, hardware, directories, and acceptance criteria. Do not copy generic skill CLI usage unless the local HWLAB copy is required for continuity.

Process Distillation

Process documents are historical records, usually timestamped and volatile.
Distillation means extracting only the stable conclusion into docs/reference/.
Process records must not be edited or rewritten during distillation.
Start with older process records and move forward; for large records, read in windows and update the reference as stable conclusions emerge.
Newer stable conclusions override older conflicting conclusions.
A reference may briefly outline important development turns, but it must not become a run log.

HWLAB Application

docs/reference/README.md is the long-term reference entry.
AGENTS.md stays the short operational index.
Process issue links such as #7, #61, #78, #99, #108, and #109 are preserved as sources in references, not copied as full timelines.
Current HWLAB rules about 16666/16667, D601 workspace paths, M3 evidence, Cloud Workbench default route, and PR workflow live in the dedicated reference files.

Local docs-spec Text

This local copy is kept so HWLAB documentation work remains governed even when the external skill body is not available in a runner.

---
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。
      - 避免将发展过程写成流水账。
      - 越早期的发展过程越简略地写。
      - 重要的发展过程节点可以交叉引用过程文档。
  - 不要篡改过程文档 - 过程文档是一手的历史资料，禁止对过程文档进行篡改。

5.9 KiB Raw Blame History