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