repo-doku

Repo 文档：在源代码仓库中编写文档

目的

此技能会直接在源代码仓库中创建或更新文档，作为唯一事实来源，供下游文档系统（文档门户、网站）使用。 文档写入 README.md；对于较大型项目，还会写入 DEVELOPMENT.md。

• 输出保留在仓库中：始终写入 README.md；只有较大型项目才写入 DEVELOPMENT.md。
• 不自动提交：绝不自行提交或推送，只提出 Conventional Commit 建议。

工作流

1. 确定文档目标

• 评估项目类型和规模（库/客户端、较大型应用、CLI 等）。
• 确定文档目标：仅 README.md，或 README.md + DEVELOPMENT.md。
• → 详见 references/doku-ziel.md。

2. 查找最近一次文档记录（Git）

找到最近一次记录文档的节点，以便只补齐缺失内容：

git log -1 --format='%H %ci' -- README.md   # letzte Änderung am README
git log --oneline <letzter-stand>..HEAD      # Commits seitdem

• 按类型对 Conventional Commits 分组（feat、fix、BREAKING CHANGE 等）。
• feat/BREAKING CHANGE 与文档相关；纯粹的 chore/ci/test 通常无关。

3. 收集来源（按以下顺序）

1. 现有文档（README.md，如有则包括 DEVELOPMENT.md）作为基础——在其基础上续写， 不要从头重写。
2. 变更日志文件作为新功能的结构化来源（注意仓库中的确切文件名，例如 Changelog.md 与 CHANGELOG.md）。
3. Git 提交记录：查找上次记录以来（步骤 2）的变更，补充未写入变更日志的内容。
4. 源代码：用于核实细节，包括公开 API、选项、签名和真实示例。

4. 编写/更新文档

• 遵守约定 → references/konventionen.md （语言、代码/注释语言、变更日志、图表、项目特定规则）。
• 尽量减少改动：只补充或更正与新增提交/功能相关的内容。
• 示例应基于真实代码，不得编造 API。

5. 收尾

如果文档有改动：

• 如果项目通常会跟踪任务，请在任务列表中记录任务（例如 todos/<thema>/todo.md）。
• 提出 Conventional Commit 建议（例如 docs: README um Feature X ergänzen）， 但不要自行提交。
• 简要总结改动。

“没有缺口”也是有效的结果。 如果评估表明现有文档已是最新且完整（例如，自上次记录以来只有内部 Bug 修复/测试/发布），则不要强行改动：不要编造内容，不要创建任务列表，也不要提出提交建议。而应简要说明已评估的来源和结论，并指出可能存在的边界案例，由用户决定如何处理。

参考资料

• references/doku-ziel.md — 选择文档目标（README 或 README+DEVELOPMENT）、 范围以及应包含和不应包含的内容。
• references/konventionen.md — 写作、变更日志和图表规则， 以及项目特定约定。