documentation-writer

documentation-writer · 基于代码事实的技术文档

路径约定：references/、scripts/、assets/ 都相对于本 SKILL.md 所在目录。运行脚本前先设 SKILL_DIR="<本 SKILL.md 所在目录>"；文档路径、仓库根等参数按目标仓填写。

这份 skill 要的文档有三个特点：说的都是仓库里真实存在的东西；读者拿到就能用（命令能跑、例子能抄、图能看懂）；读起来像熟悉这套代码的工程师写的，不像模型生成的。三者冲突时，准确优先。

选文档类型

用户要的	读者	先读	默认位置（仓库已有约定时从约定）
README：新建、补全、按代码变更同步	第一次接触项目的人	references/readme.md	仓库根或子包根的 README.md
API 文档：HTTP 接口、OpenAPI、库 / SDK 参考	调用方开发者	references/api-docs.md	docs/api/ 或服务目录下 docs/
架构文档：系统怎么搭起来、为什么这样搭	新加入的工程师、评审者	references/architecture.md	docs/architecture.md 或 ARCHITECTURE.md
代码库说明：成套的结构、约定、功能、测试、风险文档	日常改代码的人和 AI agent	references/codebase-map.md	docs/codebase/
用户手册、教程、操作指南、运维手册	最终用户、运营、运维	references/user-manual.md	docs/user-guide/ 或 docs/manual/

架构文档和代码库说明容易混。用户要一份能从头读到尾的「系统是怎么工作的」，走架构文档；要一套放在仓库里、按主题随查随用的参考（技术栈、目录、约定、功能清单、测试、风险），或者明确说「代码库说明 / 功能说明 / map this codebase」，走代码库说明。拿不准时问一句，问不了就写架构文档，并在交付说明里提一句另一种选择。

一个请求涉及多类文档（比如「给这个服务写 README 和接口文档」），按类型分别读对应参考，各写各的，互相链接，不要把 API 参考塞进 README。

不归本 skill 管：只改代码注释或 docstring、写 commit message、写 PRD（用 prd skill）、写开发计划（用 dev-plan skill）、制定迁移或现代化方案。

通用流程

每类文档都走这六步，差别在参考文件里。

1. 定读者、目的和范围

先弄清三件事：谁读、读完要能做什么、覆盖哪些不覆盖哪些。按 Diátaxis 分清这份文档属于哪一类，四类写法不同，不要混在一起：

• 教程：带新手完整做成一件事，一步一个结果，不讲原理。
• 操作指南：解决一个具体问题，假设读者已经会基本操作。
• 参考：准确、完整、结构统一，像字典，不讲故事。
• 解释：讲清楚为什么这样设计、有哪些取舍。

能从请求和仓库推断出来的，不要问。真正缺的信息一次问完。新写大文档（架构文档、用户手册、代码库说明）时，先把大纲给用户看：章节、每节一句话、打算画哪几张图，确认后再写。用户已经给了结构、说了「直接写」，或者当前环境没法提问，就把假设写进交付说明，直接写。

输出语言：目标仓已有文档用什么语言就用什么语言；仓库没有文档时用对话的语言。目标仓的 AGENTS.md / CLAUDE.md / CONTRIBUTING.md 里有文档约定（位置、格式、术语）的，照约定来。

2. 摸清事实（本地优先）

文档描述的是眼前这份代码，所以事实从本地 checkout 里取，不从记忆、网络或远端仓库取。

1. 锚定快照：git remote -v、git branch --show-current、git log -1 --format='%h %ad %s' --date=short。架构文档和代码库说明要把这三项写进文档，读者才知道描述的是哪个版本。remote URL 里如果带了凭据（https://<token>@host/...），写进文档前删掉。

2. 读真实的清单文件：package.json、go.mod、pyproject.toml、Cargo.toml、pom.xml 这类 manifest，Makefile 或其他任务脚本，CI 配置，.env.example，已有的 README / docs/。技术栈和命令以这些文件为准，不以你对框架的印象为准。栈不明确时读 references/stack-detection.md。

3. 仓库大或者陌生时先扫一遍：在目标目录下跑

   python3 "$SKILL_DIR/scripts/scan.py" --output /tmp/codebase-scan.txt
   

   会输出目录树、manifest、入口、lint 配置、环境变量模板、TODO、近期提交、高频改动文件、CI、容器、代码量。monorepo 里只写一个子包时，在子包目录里跑。扫描结果是线索，结论仍要回到源文件确认。

4. 已有文档是意图，不是事实。README 常常写的是「打算怎么做」。和代码对不上时以代码为准，把分歧记下来，交付时告诉用户。

5. 只写源码，不写产物。dist/、build/、generated/、.next/、__pycache__/、node_modules/ 里的东西不当作项目约定。

找不到答案的，网络查询是最后手段，只在事实确实影响文档、又无法从本地确定时用，而且要标 [UNVERIFIED] 说明来源。

3. 写

按对应参考文件的结构写。贯穿所有类型的规矩见下文「证据纪律」和「写作风格」。

4. 出图

见下文「出图：archify 优先，Mermaid 兜底」。

5. 自检

写完先跑检查脚本，它会核对文中引用的路径是否存在、行号是否越界，扫出凭据、没填的模板占位、AI 腔词汇和破折号密度：

python3 "$SKILL_DIR/scripts/check_doc.py" <文档路径...> --repo-root <仓库根>

脚本报「路径不存在」的逐条修掉；报 AI 腔的逐条看，确属术语或引用原文的可以保留。然后人工过一遍：

• 写到的命令都在 manifest / 任务脚本 / CI 里出现过；没亲自跑过、又有疑问的，标出来
• 例子里的字段名、取值形状来自 schema、测试或 seed，不是编的；密钥、token 用占位符
• 数量写具体数字（「13 个路由文件」），不写「很多」
• 不确定的地方都打了标记
• 图的文件存在，链接能点开
• 按 references/writing-style.md 的清单去一遍 AI 腔

6. 交付说明

回复用户时说清：

• 新建或改动了哪些文件（路径）
• 图用了 archify 还是 Mermaid；用 archify 的，列出每张图的 HTML 路径、deliver 结果和 visual-check 状态（通过 / 失败 / 跳过），不要把没做过的检查说成做过
• 所有 [ASK USER] 问题，编号列出
• 文档和代码对不上的地方（README 说 A，代码是 B）
• 写作时做的假设

根拠の規律

ドキュメントの価値は、読者が自分で再確認しなくても、そのまま信頼できることにあります。そのためには：

• 自明でない結論にはすべて出典を付けます。アーキテクチャドキュメント、コードベースの説明、API ドキュメントでは、リポジトリのルートからの相対パスと行番号を使って引用します：apps/api/src/index.ts:42 または src/routes/users.ts#L10-L35。引用する行は、実際に読んでおく必要があります。README やユーザーマニュアルの読者はソースコードを見ないため、本文に行番号の引用は載せませんが、執筆前に同じように確認してください。

• 次の4つのマーカーに統一し、意味の違いに応じて使い分けます。混同しないでください：

  マーカー	用途
  [INFERRED]	コードから推論したが、明記されている箇所がない
  [UNVERIFIED]	別の場所にある説明を転記したが、自分では確認していない（例：ドキュメントに記載されたビルド時間、CI が必須チェックかどうか）
  [TODO]	リポジトリ内で見つからず、後で補う必要がある
  [ASK USER]	チームの意図次第で、人にしか回答できない

  マーカーは英語のままにします。日本語のドキュメントでも同様です。grep しやすくするためです。

• 矛盾があれば判断し、単に伝聞として書かないでください。2つの情報源で説明が異なる場合（manifest のバージョンとコード内の定数が一致しないなど）は、コードを読んで結論を出し、「確認済み：X には A とありますが、実際に有効なのは B です。理由は……」と一文で記載します。

• 数えられるものは数えます。「service パッケージが合計73個」とあれば、確認したことが伝わります。「サービスがたくさんある」では推測に見えます。

• 見せかけの網羅性より、正直に空白を残すほうが有用です。書けない部分には [TODO] と記し、曖昧な表現で埋めないでください。

図の作成：archify を優先し、Mermaid を代替として使う

図が必要かどうかをまず考える

図は、文章だけでは説明しにくい内容、たとえばコンポーネント同士の接続、システムを通るリクエスト、状態の流れを表すために使います。3ステップ以内の直線的なフローなら、一文か番号付きリストで十分です。通常、1つのドキュメントに図は1〜4枚とし、各図について、何を示すものか、読者がどこに注目すべきかを本文で一文説明します。

archify の利用可否を確認する

Agent は現在の環境で利用可能な skill の一覧を自分で確認します。一覧に見つからない場合、または一覧が提供されていない場合は、この skill と同じ階層のディレクトリ、および現在の環境にあるプロジェクトレベルとユーザーレベルの skill ディレクトリから archify/SKILL.md を探します。見つかったら読み込むか内容を確認し、その手順に従って図を作成します。インストールされていない場合は Mermaid を使います。archify のインストール確認スクリプトを新たに作成したり、実行したりしないでください。skill を自動インストールしないでください。

archify で図を作成する

JSON の記述方法、検証方法、レイアウトの修正方法は、すべて archify の SKILL.md に従います。ここでは繰り返しません。この skill では、ドキュメントとの連携に関する部分のみを定めます：

種類の対応

ドキュメント内の図	archify の種類
システムコンテキスト図、コンテナ図、デプロイトポロジー、モジュール依存関係	architecture
リクエスト経路、API 呼び出しシーケンス、認証 / token 交換ハンドシェイク	sequence
ビジネスプロセス、承認フロー、CI/CD、操作手順	workflow
データパイプライン、ETL、データリネージ、イベントフロー	dataflow
ステートマシン、注文やタスクの状態遷移、リトライと終端状態	lifecycle

ファイルの配置：ドキュメントのあるディレクトリの下に diagrams/ を作成し、ソースファイルと生成物の名前を一致させます：docs/diagrams/system-context.json と docs/diagrams/system-context.html。後から図を変更できるよう、ソース JSON を残します。

図中のテキストはドキュメントと同じ言語にします。中国語のドキュメントでは meta.locale: "zh-CN" を設定します。ノード名、API パス、コマンドなどの識別子は原文のままにします。

Markdown への配置方法：まず archify の deliver を実行し、次に visual-check を実行します（ローカルに Chrome / Chromium が必要です）。visual-check が成功すると、HTML の隣にスクリーンショット <名前>.visual-check.1440x900.light.png が生成されます。これを本文に埋め込み、その下にインタラクティブ版へのリンクを記載します：

![系统上下文图](diagrams/system-context.visual-check.1440x900.light.png)

交互版：[diagrams/system-context.html](diagrams/system-context.html)，用浏览器打开，可缩放、搜索、追踪调用链。

visual-check が失敗した場合、または実行をスキップした場合は、インタラクティブ版へのリンクのみを配置し、スクリーンショットが生成されていないことを納品説明に記載します。同じ図を Mermaid でも作成しないでください。2つを別々に変更して、最終的に内容が食い違うことになります。

残すファイルは3つのみ：各図について、リポジトリに残すのは <名前>.json（ソース）、<名前>.html（インタラクティブ版）、および本文に埋め込む <名前>.visual-check.1440x900.light.png の3つです。visual-check が別途生成するダークモード版や2048サイズのスクリーンショット、<名前>.visual-check.html の概要ページ、<名前>.visual-check.json のレシートはすべてチェックの証跡です。チェック結果を納品説明に記載した後で削除してください。そうしないと、1枚の図につき diagrams/ に8つのファイルが残ります。

修正できなければ切り替える：archify の修正手順を2回続けても改善しない図は、その図に限り Mermaid に切り替えます。理由と archify のエラー内容を納品説明に記載します。

Mermaid で図を作成する

• 種類：構造には flowchart、シーケンスには sequenceDiagram、状態には stateDiagram-v2 を使います。
• 1枚の図のノード数は12個以下にします。超える場合は2枚に分けるか、主要な流れのみを描きます。
• ノードのラベルには読者が認識できる名前（サービス名、モジュール名）を使い、内部変数名は使いません。
• 図のすぐ近くの本文に、その図が何を示しているかを一文で記載します。
• 納品説明には、archify をインストールすれば、インタラクティブでエクスポート可能な図を作成できることに触れます（リポジトリの URL は https://github.com/tt-a1i/archify）。この説明は1回だけにし、繰り返し宣伝しないでください。

執筆スタイル

技術ドキュメントから AI らしさをなくすには、個性を加えるのではなく、具体的で、直接的で、検証可能な内容にします。完全なチェックリストと中国語・英語の例は references/writing-style.md にあります。執筆後に照らし合わせて確認してください。特に重要な点は次のとおりです：

• 冒頭で、何についての文書か、誰向けか、何ができるかを直接説明します。「昨今の……を背景に」「……が急速に発展する中で」といった表現は使いません。
• 中身のない表現を削除します：エンパワーする、支援する、構築する、ワンストップ、包括的、シームレス、強力な、究極の、深く統合する、注目すべき、総括すると。英語では delve、leverage、seamless、robust、comprehensive、cutting-edge も同様です。削除すると文が成り立たない場合、元から内容がなかったということです。具体的な事実（数値、名前、動作）に置き換えます。
• 見出しやリストに絵文字を付けません。「パフォーマンス： パフォーマンスが向上します」のような太字の小見出し付きリストは使いません。参考資料で使われる「用語：定義」の形式は一般的なので、使用できます。
• 用語を一貫させます。同じものを最初に「テナント」と呼んだら、その後も「テナント」と呼びます。「組織」「スペース」「チーム」と呼び替えないでください。
• まとめや展望で締めくくらないでください。説明が終わったら、そこで終わりにします。
• 参考資料は中立的に保ちます。一人称や個人的な見解は加えません。チュートリアルや README では「あなた」と呼びかけても構いません。実際に遭遇した問題（「初回に db:migrate を実行すると失敗します。Redis がまだ起動していないためです」など）を記載するのも、技術ドキュメントに適した人間らしさです。
• 既存ドキュメントを更新する場合は、その文体を引き継ぎます：見出しの階層、用語、絵文字の使い方、中国語と英語の混在方法などを既存のスタイルに合わせます。追加・変更した部分に AI らしい表現がないことだけを確認します。

既存ドキュメントの更新

「ドキュメントを同期して」「README が古い」「API が変わったのでドキュメントを更新して」といった依頼を受けた場合：

1. まず既存のドキュメントを通読し、次にコードの変更を確認します（git diff、git log -p -- <パス>、またはユーザーが説明した変更）。
2. ドキュメントのうち現状と一致しない箇所を列挙し、変更する段落と一つずつ対応させます。コード変更とドキュメントのセクションの対応関係は、references/readme.md の「変更マッピング」を参照してください。
3. 変更が必要な段落だけを編集し、構成、語調、形式はそのまま維持します。機会に乗じて文書全体を書き直さないでください。
4. すでに存在しない機能、パラメーター、コマンドは削除します。追加するだけにしないでください。
5. 納品説明には、変更した箇所と、その理由を記載します。

参考文件索引

文件	什么时候读
references/readme.md	写或更新 README
references/api-docs.md	写 HTTP 接口文档、OpenAPI、库 / SDK 参考
references/architecture.md	写架构文档、系统设计说明
references/codebase-map.md	写 docs/codebase/ 成套说明
references/inquiry-checkpoints.md	写代码库说明时，每份文档要回答的问题
references/user-manual.md	写用户手册、教程、操作指南、运维手册
references/writing-style.md	每次交付前，去 AI 味
references/stack-detection.md	技术栈不明确、多种 manifest 并存时
assets/templates/*.md	代码库说明的八份模板
scripts/scan.py	大仓或陌生仓，动笔前扫描
scripts/check_doc.py	交付前自检