wikikit

wikikit

読者が開くドキュメントです。このプロジェクトの実行方法、目的の作業だけを行う方法、構成の仕組み、そして午前3時にダウンしたときの対処方法を示します。wikikit は、実際のコードベースからこの一式を生成し、コードの変更に合わせて内容を正確に保ち、古くなった場合は正直に報告します。GitHub Wiki タブのことではありません。wikikit が作成するものはすべてリポジトリ内の Markdown で、コードと一緒にバージョン管理され、同じプルリクエストでレビューされるためです。この一式を wiki タブにミラーリングする機能は、名前を指定して明示的に要求した場合にのみ実行される、オプトイン方式の publish モードとして利用できます。

エージェントが構築したリポジトリには、計画、レビュー、QA ドキュメント、意思決定記録が蓄積される一方で、1年前にスキャフォールドが書いたままの npm install とだけ書かれた README が残ることがあります。ナレッジは存在していても、プロジェクトの外にいる人が読むことのない成果物に散らばっているだけです。wikikit は、外部の読者に向けた側を担います。

wikikit が担わないこと

• GitHub Wiki ではありません。 どのモードでも、リポジトリ内の Markdown が唯一の信頼できる情報源です。コードと一緒にバージョン管理され、同じ PR でレビューされます。wiki タブはせいぜい派生した使い捨て可能なミラーであり、名前を指定して publish を要求した場合に限られます。wikikit は wiki を入力として読み込まず、正規の情報源として扱うこともありません。
• ドメインモデルではありません。 用語集（CONTEXT.md）と意思決定記録（docs/adr/）の所有者は1者です。domainkit がインストールされている場合は domainkit、それ以外の場合は人間が所有します。用語が必要なページは用語集を参照し、用語の定義は行いません。根拠が必要なアーキテクチャページは、言い換えるのではなく ADR を番号で参照します。用語集にない用語は、インラインで創作せず、適切な担当へ回します。CONTEXT.md に ## Overview がある場合、製品の目的を述べるページはその概要を参照し、改めて説明しません。また、architecture.md はそのリンクから始めます。
• プロセス成果物ではありません。 計画、QA 計画、レビュー、引き継ぎ、エージェント向け指示ファイル（CLAUDE.md および同等のファイル）は、作業中のメンテナー向けに書かれ、時間とともに古くなるものであり、読者向けドキュメントの信頼できる情報源として読まれることも、このスキルが作成することもありません。
• API リファレンス生成ツールではありません。 TypeDoc、Sphinx autodoc、OpenAPI 仕様などの生成ツールがある場合、wikikit はその出力を変更せずにリンクします。1週間以内に内容が乖離するようなリファレンス資料を手書きすることはありません。

実行されるタイミング

• init。 「このプロジェクトのドキュメントを書いて」「このリポジトリを文書化して」「ドキュメントがない」「はじめにのガイドを生成して」などの依頼。コードベースからドキュメント一式を初期生成します。
• update。 「ドキュメントを更新して」「この変更後にドキュメントが古くなっている」「機能の追加直後にドキュメントを見直して」などの依頼。変更によって無効になった箇所だけを更新します。
• audit。 「ドキュメントが古くなっていないか」「コードと照らして確認して」「文書化されていないことは何か」などの依頼。読み取り専用で調査します。決して何も書き込みません。
• publish。 明示的な依頼があった場合のみ。 「ドキュメントを GitHub wiki に公開して」「docs/wiki/ を wiki タブに同期して」「wiki のアクションを設定して」などの依頼。ドキュメント一式を wiki にミラーリングするワークフローをインストールします。

どのモードか明確でない場合は、質問してください。 audit は無料で実行できますが、init は十数個のファイルを書き込みます。両者を決して推測で選ばないでください。

publish を推測で実行することはありません。 ドキュメント更新の通常の流れには含まれず、ほかのモードから移行することもありません。また、「ドキュメントが古くなっている」や「ドキュメントを公開して」という依頼だけの場合は、このモードではなく update を意味します。GitHub wiki、wiki タブ、または同期ワークフロー自体が依頼に明記されている場合に限り実行されます。依頼したことのないリポジトリに、この機能の存在を知らせることもありません。

ドキュメント一式の場所を特定する

どのモードも同じ方法で開始するため、読み取りや書き込みを行う前に、3つのモードすべてでドキュメントの場所を確認できます。見つかった一式はすべて、モードの出力の最初の行に名前を記載してください。 空の結果から推測するのではなく、見つからなかった一式がすぐにわかるようにするためです。

既存のセットを探す

**/.wikimap.yaml のグロブを1つ使用し、リポジトリのルートとワークスペースのグロブ（pnpm-workspace.yaml、package.json の workspaces、go.work、Cargo ワークスペース）の範囲に限定して検索します。.gitignore に従うことで、ベンダー化されたツリーからセットが持ち込まれないようにします。ルートレジストリはありません。マニフェストは説明対象のセットとともに置かれ、後から追加されたセットも自動的に見つかります。

セットのないリポジトリで検出ラダーを実行する

最初に一致した段を採用し、書き込みを始める前にどの段に一致したかを伝えてください。

#	段	ドキュメントの保存先
1	設定済みのドキュメントエンジン：mkdocs.yml、docusaurus.config.*、.vitepress/、Starlight を使用する astro.config.*、conf.py、Nextra の設定	そのエンジンで設定されたコンテンツディレクトリ。ナビゲーション／サイドバーも同じ処理で更新します
2	既存の閲覧者向けドキュメントツリー：エージェントの成果物ディレクトリだけではない、内容のある docs/、または documentation/、website/docs/	そのまま採用し、移行しません
3	フォールバック	初回の書き込み時に作成する docs/wiki/

docs/wiki/ を使うと、docs/ を親ディレクトリとして共有するエージェントの成果物ディレクトリから閲覧者向けドキュメントを隔離できるため、閲覧者が QA 計画にたどり着くことはありません。ただし、既存のエンジンが常に優先されます。wikikit はリポジトリがすでに実行しているサイトに書き込み、エンジンがないリポジトリに MkDocs や Docusaurus を新たに導入することはありません。

ワークスペースでは、常にルートのセットを書き込みます。パッケージが独自のセットを持つのは、個別に公開されるか、単独で実行できる場合に限ります。 まずルートでラダーを実行し、次に条件を満たす各パッケージ（packages/<x>/docs/）で実行します。書き込みを始める前に、分割方針を伝えてください。ルートのみにすると、4つほどのパッケージを超えたあたりでアーキテクチャのページが使いものにならなくなります。一方、常にパッケージごとに分けるのも、閲覧者が1つの「はじめに」を求めるアプリのモノレポでは適切ではありません。

マニフェストとディスク上の状態を照合する

中央マニフェストは、正しく見えていても実際には誤っている可能性がある唯一のマップ形式です。そのため、すべてのモードで作業開始前に必ず次の点を確認します。

• マニフェストにエントリがない、ディスク上のページ
• ページが存在しないエントリ
• 何にも一致しない documents: のグロブ
• ラダーの判定と一致しなくなった home:。通常は init の後にドキュメントエンジンが導入されたケースです

init と update は、同意が得られれば修正します。audit は差分を独立した行として報告するだけで、何も書き込まないため修正は行いません。移行が暗黙に行われることはありません。以前は段3に一致していた場所で段1に一致するようになった場合は、両方のパスを示し、同意を得たうえで git mv とナビゲーションの更新を1つの手順として提案します。同意が得られなければ、wikikit はマニフェストに記載された場所への書き込みを続け、実行のたびに不一致を報告します。

ドキュメントマップ

ドキュメントマップは、3つのモードすべてが操作する単位です。<doc home>/.wikimap.yaml に置きます。ドットで始まるファイル名にすることで、GitHub のフォルダ表示と各エンジンのビルドの両方で、設定を変更しなくても除外されます。このファイルには、ページごとにDiátaxis のモードと、そのページが説明するコードのグロブが記載されています。

home: docs/wiki
engine: none                    # or mkdocs | docusaurus | vitepress | starlight | sphinx | nextra
pages:
  - path: getting-started.md
    mode: tutorial
    documents: [package.json, src/index.ts, .env.example]
  - path: how-to/deploy-to-staging.md
    mode: how-to
    documents: [.github/workflows/deploy.yml, infra/**]
  - path: architecture.md
    mode: explanation
    adopted: true               # a human wrote it; wikikit maps it, never claims it
    documents: [src/**]

documents: があることで、コードパスからページを特定する検索が可能になり、すべてのページを読む必要がなくなるため、update が高速になります。また、audit の更新日時による事前フィルターにも使われます。

ページの用語体系

ページ	Diátaxis のモード	内容
index.md	なし	エントリーポイントと目次
getting-started.md	チュートリアル	インストール → 実行 → 初めての成功
how-to/<task>.md	ハウツー	1 ページにつき 1 つのタスク。目標に沿った構成
how-to/set-up-a-dev-environment.md	ハウツー	貢献者向けドキュメントのうち、リポジトリから導き出せる部分
how-to/cut-a-release.md	ハウツー	リポジトリに実際に存在するリリース手順
architecture.md	解説	CONTEXT.md の概要が存在する場合は、そのリンクから始める。コンポーネント、境界、データフロー、ADR へのリンク
runbooks/<scenario>.md	ハウツー（運用者向け）	デプロイ、ロールバック、インシデント対応、バックアップ／復元
reference.md	リファレンス	宣言されたインターフェースのみ：コマンド、フラグ、環境変数、設定キー

この表は用語体系であり、ノルマではありません。 構成はリポジトリから導き出します。デプロイのないライブラリにはランブックはなく、CLI にはコマンドのページがあり、TypeDoc のビルドがあるリポジトリには reference.md はまったくありません。

Diátaxis は内部で適用し、読者の目には触れないようにします。4 つのモードは、ドキュメントの種類を混在させないための規則であり、ページに印字する専門用語ではないためです。ハウツーを解説に逸脱させてはならず、アーキテクチャのページをチュートリアルに変えてはなりません。

この用語体系が定める 3 つの境界：

• CONTRIBUTING.md はリンクするだけで、作成しません。 開発環境の設定とリリース手順はリポジトリに存在し、他のハウツーと同じように検証できます。PR のマナー、行動規範、レビューの慣習はコードには存在しない社会的な取り決めであり、それらを書くことは、リポジトリで最も目につく貢献者向けページにおいて、根拠に基づくという規則に反します。ファイルが存在する場合、index.md からリンクします。
• reference.md で扱うのは宣言されたインターフェースのみです。つまり、単一の場所で宣言され、単一の grep で再検証できるものです。CLI コマンド、フラグ、環境変数、設定キーが該当します。ライブラリのシンボルや手作業で管理する HTTP エンドポイントの一覧は対象外とし、ジェネレーターに任せます。この狭い例外があるのは、フラグが 20 個ありドキュメント作成ツールのない CLI に、何もないよりは情報を提供するためです。
• ミラーページは作成しません。 ミラーページとは、すでに自分自身を説明している単一のソースファイルを書き直したページです。各スキル、プラグイン、モジュール、コマンド、パッケージについてそれぞれページを作り、各自の README、SKILL.md、ドキュメントコメントをコピーするものです。ソースを編集するたびに二重の編集が必要になり、コピーはメンテナンスされているように見えながら内容が古くなります。このような一連の項目は、各項目を 1 行で紹介してそのソースにリンクする1 つのインデックスページでまとめます。リポジトリにスクリプトがある場合は、ソース自身のメタデータから生成します。ページを作る価値があるのは、単一のソースファイルでは説明できないこと、つまり各部分のつながり、複数の部分にまたがるタスクの手順、問題が起きた際の対処を伝える場合です。このコストを説明したうえでユーザーが求めた場合に限り、ミラーの連続ページを作成し、その選択をマニフェスト項目のコメントに記録します。

プロベナンススタンプ

wikikit が作成するすべてのページは、次の1行で終わります。

_Verified against `main`@`a1b2c3d` on 2026-08-06._

どちらの部分にも意味があります。audit は SHA がまだ参照可能な間はその SHA との差分を調べ、リベースやスカッシュマージによって参照できなくなった場合は日付にフォールバックします。そのため、可能なときは正確に判定し、正確にできないときは嘘をつかずに精度を下げます。

スタンプは、ページ上のすべての主張が検証済みであり、その SHA がデフォルトブランチ上のコミットであることを示します。 変更によって移動した主張だけでなく、ページ全体を確認する検証パスを完了してから、ページにスタンプを付けてください。フィーチャーブランチ上では、検証済みのコミットはまだデフォルトブランチに存在しないため、古いスタンプをそのまま残してください（新しいページにはスタンプを付けません）。マージ後にスタンプが必要なページとして、引き継ぎ時にそのページ名を伝えてください。オペレーターはマージ後、デフォルトブランチ上でスタンプを付けます。それまでは audit が引き続きスタンプが必要だと報告します。

スタンプのないページは古いのではなく、未検証です。 これが、取り込まれたページを示す方法です。ランク2の下で見つかったページには、documents: グロブと adopted: true を含むマニフェストエントリーが作成され、スタンプは付きません。wikikit はそのページを認識して参照できますが、そのページ上の主張を一度も確認していません。検証パスで初めて実際にページ全体が確認されたときに、最初のスタンプが付与されます。取り込みはマッピング作業であり、人間が書いた文章の著者であると主張することではありません。

根拠の確認：書く前に検証する

出荷する前に、すべての事実に関する主張をリポジトリで検証します。 コマンドは実際の package.json、Makefile、pyproject.toml、または justfile から確認します。パスが存在し、環境変数が実際にどこかで読み取られ、エンドポイントが実際にルーティングされていることを確認します。コードから見つけられない機能を、wikikit はドキュメントに記載しません。 これがドキュメント一式と、もっともらしいだけの作り話を分ける唯一のルールであり、3つすべてのモードに適用されます。

静的な読み取りがデフォルトであり、証明できるのはスクリプトが宣言されていることまでで、実行できることではありません。そのため wikikit は、実行ごとに1回の同意確認の後、副作用のない固定の許可リストにあるプローブを実行する場合もあります。

許可	禁止
<command> --help、-h	インストールを行うもの（npm install、pip install、brew）
<command> --version、-V	ビルド、コンパイル、バンドルを行うもの
make -n <target>、make help	データベースを移行するもの、またはデータをシードするもの
スクリプトの一覧表示のみ（npm run、pnpm run、yarn run、just --list）	デプロイ、公開、プッシュを行うもの
読み取り専用の git コマンド（git log、git diff、git show、git rev-parse）	ドキュメント一式の外部に書き込むもの、または稼働中のサービスを呼び出すもの

許可リストはここに記載したものであり、推測して追加することはありません。無害に見えてもリストにないコマンドは実行しないため、その主張は未検証として報告してください。audit における「読み取り専用」とはファイルを書き込まないという意味なので、ここでもプローブを利用できます。プローブが最も役立つのはこのモードです。

モード

モードの本文はそれぞれ modes/ の個別ファイルにあります。When this fires に従ってルーティングし、該当するファイルを1つ読み、その指示に従ってください。この行より上の内容はすべてのモードに適用され、モードの各ファイルでは繰り返しません。

• モード init → modes/init.md を読み、その指示に従ってください。
• モード update → modes/update.md を読み、その指示に従ってください。
• モード audit → modes/audit.md を読み、その指示に従ってください。
• モード publish → modes/publish.md を読み、その指示に従ってください。

執筆基準

ドキュメントと、生成された中身のない文章を分けるルールです。

• 意図と使い方を記述し、仕組みの説明はコードに任せます。 関数の動作を一行ずつ説明するページは、関数そのものより劣ります。
• リポジトリに現時点で含まれていることだけを記述します。 リポジトリにないものは、ドキュメントにも記載しません。
• 1ページにつきDiátaxisのモードは1つです。 ハウツーでは1つの目標に答え、アーキテクチャの説明は解説ページに任せます。解説ページは最後まで解説に徹します。
• 最初に役立つ文から始めます。 ドキュメントの概要を説明する文は、読者に読み飛ばされます。
• すべてのコマンドはコピー＆ペーストでき、検証済みでなければなりません。 実際のフラグ、実際のパス、実際の名前を使います。
• ハウツーのタイトルはタスクに即したものにします。 「デプロイ」ではなく「ステージング環境にデプロイする」とします。

ダッシュの多用、三段構成の繰り返し、曖昧な表現、宣伝文句など、AI が書いた文章によく見られる特徴には、インストール済みであれば humankit による仕上げを提案してください。wikikit では、この一覧を重複して掲載しません。

注記

• GitHub Wiki への公開はオプトインであり、明確に制限されています。デフォルトではありません。 publish は存在しますが、そこへ誘導する処理はありません。ループが公開を提案することはなく、リクエストでWikiを指定する必要があります。この制限があるのは、ミラーが破壊的かつ一方向だからです。そのため、Wiki の編集ボタンは引き続き機能しますが、Wiki 上で行った編集は次回の同期時にすべて失われます。Wiki を人が 執筆する 場所として扱うリポジトリでは、これをインストールしないでください。Wiki を docs/wiki/ のレンダリング結果として扱うリポジトリでは、インストールしてください。
• Wiki は常に下流にあります。 wikikit がWikiを信頼できる情報源として読み取ることはなく、編集内容を自動的にリポジトリへ反映することもなく、Wiki に対して audit を実行することもありません。Wiki とドキュメント一式の内容が異なる場合、定義上、正しいのはドキュメント一式です。
• 操作ごとに同意を求めます。 init のマップ、新しいページ、削除、README マーカー、ドキュメントのホームの移行、プローブの実行では、いずれも確認を求めます。update による既存ページの編集では確認を求めません。編集は制約ルールにより範囲が限定され、レビュー可能な差分として反映されるためです。audit では、何も変更しないため、プローブ以外について確認を求めません。
• 変更を伴う実行は一切行いません。 プローブの許可リストは固定され、副作用はありません。主張を検証するために、wikikit がインストール、ビルド、移行、デプロイを実行することはありません。そのため、検証できない主張は、実際に検証を試みるのではなく、未検証として報告します。
• ドキュメントサイトの基盤は追加しません。 wikikit は、すでに存在するエンジン向けにコンテンツを書き、ナビゲーションを更新します。新しいエンジンを追加することはありません。
• マーケティング文言も翻訳も扱いません。 ランディングページ、機能紹介、変更履歴、ローカライズはすべて対象外です。
• 既存のプロジェクト規約を優先します。 独自のドキュメントの保存場所、ページ命名規則、エンジン構成があるリポジトリでは、規約を上書きせず、それに従います。wikikit は、どの規約に従ったかを明示します。
• ファイルシステムを使えない場合（ブラウザーベースのエージェントなど）は、各ページをパスをラベルとして付けたフェンス付きコードブロックで出力し、マニフェストも同じ形式で出力して、ユーザーが自分で実行すべきプローブの名前を示します。実際には書き込めなかったページを、書き込んだと報告してはいけません。