ドキュメントマネージャー
人間とAIエージェントのためのプロジェクトの生きたナレッジ。コードが方法と主張の真偽の真実の源泉です。 AGENTS.md + docs/ は何を、なぜ、決定、計画を捉えますが、コードと矛盾する場合は決してコードを上書きしません。
コアルール
- ハブとして**
AGENTS.md**を優先します。agents.mdがすでに存在する場合はそれを使用します。CLAUDE.mdのみ存在する場合は、ドキュメントインデックスで拡張するか、AGENTS.mdを追加して相互リンクします — 3つの競合するハブを作成しないでください。 - 生成/更新されるすべてのドキュメントは、ハブおよび関連ドキュメントへの相対的なMarkdownリンクを使用します。
- 理由なく永続的な知識を削除しないでください。ADRには**「廃止済み」**メモを優先します。
- 自動コミットや自動プッシュは行わないでください。git操作はユーザーに任せます。
- 生成されたコンテンツはユーザーの言語（またはリポジトリの主要言語）で記述します。このスキル本文はエコシステム互換性のために英語です。
- 量よりも正確さと有用性を優先します。まずコアセットを作成し、必要に応じてオプションのドキュメントを作成します。
- まず意図（プロジェクトレベル）を決めます。 意図を分類します：
integrate|audit|from-zero（およびオプションのハイブリッド）。ステップ0を参照。純粋な機能/計画/同期には必須ではありません。 - 矛盾した場合、コードが優先されます。 構造検証に失敗したドキュメントの主張は「矛盾」または「欠落」としてマークされます — ドキュメントに合わせてコードを作成するのではなく、ドキュメントを修正するかフラグを立てます。
- まず統合（Intent=integrateの場合）。 成熟したドキュメント → インデックス + ギャップ + 正規リンク。製品ビジョン/要件/ADRの並行書き換えは行いません。adopt-integrateを参照。
- トピックごとに1つの権限。 各トピックには1つの正規ドキュメントがあります。それ以外はすべてリンクします。
- adopt/from-zeroプロジェクトのカバレッジマトリックス。 製品表面（ナビゲーション、ModuleId、パッケージ）が文書化/リンク/ギャップとして表示されます。
- 機能の原子性。 1つのスラッグ ≈ 1つのModuleIdまたは境界付けられたコンテキスト。クラスター = インデックス + 子。
- ステータスの分類。 references/status-taxonomy.md。
- サンドボックスのオプトイン / ファーストクラスのfrom-zero。 ユーザーが要求した場合（
test/など）、Out: sandbox:path。サンドボックスハブはSSOTではない旨のバナー + 昇格計画を表示します。 - 機能自動操縦（v1.5 / v2）。 単に「新機能X」/「documentá X」と言うと、スキルは計画か機能パックを選択し、デフォルトの非書き込みを適用し、種類（新機能 | スパイク | エピック | リデザイン）を設定します。実装ブリッジ（配置/スタブ）はオプトイン時のみ（「implementá」、「stubs」、「scaffold」）— デフォルトはドキュメントのみ + 1行のヒント。modes.md §3 および implementation-bridge.md を参照。
- 計画モード（v1.3+）。 未開拓の機能アイデアは、偽の実装パックや完全なプロジェクトブートストラップではなく、
docs/plans/<slug>/に配置します。コードが実際に存在する場合（スタブのみではない）、docs/features/<slug>/に昇格します。 - ArkGateブリッジ（v1.4）。 ArkGateが検出された場合（
ark.config.json、ark-check、.ark/、arkスキル）、またはユーザーがゲートを通過したばかりの場合は、ブリッジサブフローを実行します：契約からインベントリを強化します。ゲート通過後は、スコープ付きの同期 / 監査を実行します。残存する違反は、主張を「矛盾」または「部分的」としてマークします — 壊れたアーキテクチャを許容するためにドキュメントを書き換えることは決してありません。Arkなし → 何もしません。実装ブリッジの配置ヒントは、検出された場合にArkレイヤーを再利用します。arkgate-bridge.md および modes.md §9 を参照。 - ナレッジダッシュボード（v1.6）。 計画/機能/主張のオプションの静的HTMLビュー（
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html）。MarkdownがSSOTです。HTMLはgitignoredな表示専用です。監査後に一度、または「dashboard」リクエストがあった場合に提供します。knowledge-dashboard.md および modes.md §10 を参照。 - スキル強化（v1.7）。 メンテナー：リリース前に
validate-skill.sh+test-skill-hardening.shを実行します。エージェント：skill-discovery.md を介してインストール/バージョンを検出します。古い場合は再インストールを提案します（サイレント自動パッチは行いません）。 - v2.0パッケージ。 10倍のラインを完了：機能1.4～1.7 に加え docs/adoption-matrix.md の追跡。ベースラインインストールフロアは 2.0.0 のまま。多言語対応 2.1.0。モノレポ 2.2.0。チーム 2.3.0。ブリッジ完全版 2.4.0。現在のラインは 2.5.0+（ナレッジOS 100倍に向けた最初の増分 — 生きた主張 + CI監査。2回目の10倍ではありません）。
- 多言語スタック検出（v2.1 スライスA / スキル2.1.0）。 プロジェクト発見時（統合/監査/ゼロから/採用）、skill-discovery.md 多言語スタック検出（または
scripts/detect-stack.sh）を介してファイルシステム（package.json、pyproject.toml、go.mod、...）からスタックを検出します。スタック別インベントリおよびスタック別ドキュメントレイアウトガイダンスを使用します — Node/TSを想定しないでください。コードエビデンスなしにフレームワークのModuleId/エンドポイントを発明しないでください。modes.md §0.3 を参照。 - モノレポハブ（v2.2 スライスB）。 skill-discovery.md モノレポハブ（または
scripts/detect-packages.sh）を介してマルチパッケージツリー（pnpm-workspace.yaml、package.jsonworkspaces、go.work、マルチパッケージディレクトリ）を検出します。ルートハブはマップ + パッケージインデックスであり、ダンプではありません。マルチパッケージカバレッジはギャップパッケージをマークします。ルートのみのインデックス作成時は、デフォルトでパッケージ非書き込みにします。modes.md §0.4 を参照。 - チームガバナンス（v2.3 スライスC）。 オプションの
docs/team/にオーナー + 承認ノート（最終承認済みスタイル）を配置します。team-governance.md に従って作成するかリンクします。ハブはチームにリンクしますが、人事Wikiにはなりません。まず統合 — チームを追加しても、製品ビジョン/要件/ADRを書き換えてはいけません。CODEOWNERSエンジンやBPMはありません。modes.md §11 を参照。 - テンプレートテレメトリー（v2.4 スライスD）。 テンプレート/スキルUXギャップのみのためのオプトインのローカル台帳（template-telemetry.md;
scripts/template-telemetry.sh）。デフォルトオフ。ソース/シークレット/リポジトリURLは決して送信しません。ネットワークには絶対にアクセスしません。オプトインオフの場合、エアギャップ状態で何もしません。modes.md §12 を参照。 - 生きた主張 + CI構造監査（v2.5 / ナレッジOS最初の増分）。 監査マトリックスは生きた主張 v0 を使用します：
anchor.path/ オプションのanchor.symbol/ オプションのanchor.hash、severity（critical|normal）、判定は変更なし。マトリックスファースト（audit-template.md）。手順は living-claims.md。ワイヤーは ADR-0001。真実スコアは参考値（ダッシュボードヒューリスティック）のまま。ローカルエアギャップscripts/audit-claims.sh/ 例docs-auditCIがゲートです（重要な矛盾で失敗）。SaaSはありません。modes.md §6 / §13 を参照。
ステップ0 — スコープ、モード、意図を検出
スコープ（必須）：
| スコープ | タイミング | 出力の焦点 |
|---|---|---|
| project | 製品全体 / 「プロジェクトのドキュメント」 | ハブ + プロジェクトドキュメント（意図に応じて） |
| feature | 名前付き機能/モジュールコードあり（またはリフレッシュパック） | docs/features/<slug>/ + ハブリンク |
| plan | 名前付き新機能/エピック コードがない、または不十分な場合 | docs/plans/<slug>/ + ハブリンク |
| hybrid | ハブがない場合の機能/計画 | パックまたは計画 + 最小限のハブ |
モード（必須）：
| モード | シグナル |
|---|---|
| bootstrap | グリーンフィールド、ハブ/ドキュメントなし、または空/薄い状態での意図from-zero |
| adopt | コードあり。ドキュメントが薄い/ない、または意図integrate |
| audit | 「ドキュメントを監査」、「ドキュメント vs コード」、「ドリフト」、「主張を検証」 |
| plan | 「新機能」、「計画」、「エピック」、「vamos a construir X」でコードなし |
| feature | コードがある（またはコードである）1つの機能/モジュールを文書化 |
| sync | 変更のための差分 / PR / ドキュメント更新。Arkが通過したばかりの場合はポストゲート |
| roadmap | リリース/エピックリストのリフレッシュを計画 |
意図（プロジェクトレベルの作業にのみ必須）：
| 意図 | ユーザーシグナル（例） | 動作 |
|---|---|---|
| integrate | 「ドキュメントを改善」、「整理」、「ハブを同期」、「成熟改善」 | adopt-integrate（または薄い場合はフル）。ドリフトが疑われる場合はオプションの事前監査 |
| audit | 「監査」、「ドキュメントは嘘をついているか？」、「コード vs ドキュメント」、「パスを検証」 | コードインベントリ + 主張マトリックスのみ（その後引き渡し） |
| from-zero | 「すべて新規」、「ゼロから」、「test/にドキュメントを生成」、「フォルダXにフルKB」 | 完全なナレッジベース。パスが指定されている場合はサンドボックスを優先。コードから推測。古いドキュメントは仮説のみ |
推論（質問しすぎないこと）：
- 「nueva feature X」/ 「new feature X」/ 「quiero agregar X」 → 機能自動操縦（コードがない場合は計画、コードがある場合は機能。フレーズから種類を決定）。意図 = n/a
- 「implementá X」/ 「generá stubs」/ 「scaffold X」 → 必要に応じて自動操縦ステージA + 実装ブリッジオプトイン（スタブが要求された場合のみコード）
- 「generá toda la documentación en
test/」 → 意図: from-zero | Out: sandbox:test/ - 成熟したリポジトリ + 「mejorá / integrá / indexá」 → 意図: integrate
- 「auditar docs」/ 「código vs docs」 → 意図: audit
- 既存の
docs/を持つあいまいなプロジェクト作業 → 1回質問：integrate | audit | from-zero - 名前付きの単一表面 → 決してユーザーに非書き込みをリストアップさせたり、フォルダを選択させたりしないでください
- 「after ark-check」/ 「post-gate docs」/ ゲートが実行されたばかり + ドキュメント意図 → 同期または監査 + ArkGateブリッジ
- 「dashboard」/ 「docs HTML」/ 「knowledge report」 → ナレッジダッシュボードを生成（knowledge-dashboard.md）
- 「owners」/ 「quién es dueño」/ 「team docs」/ 「approval notes」/ 「docs/team」 → チームガバナンス（team-governance.md; モード §11）
- 「template telemetry」/ 「opt-in telemetry」/ 「record template gap」 → ユーザーがオプトインした場合のみテンプレートテレメトリー（template-telemetry.md; モード §12）; デフォルトオフ
- 「living claims」/ 「truth score」/ 「docs CI」/ 「fail on Contradicted」 → 生きた主張 + ローカルCIゲート（living-claims.md; モード §13）
成熟度（関連する場合）：thin | mixed | mature — modes.md を参照。
推論後もスコープ/モードがあいまいな場合は、1回質問します。references/modes.md から手順を読み込みます。
書き込み前に発表：
スコープ: <x> | モード: <y> | 意図: <integrate|audit|from-zero|n/a> | バリアント: <full|integrate|arkgate-bridge|n/a> | 成熟度: <…|n/a> | Out: <root|sandbox:path> | スタック: <node-ts|python|go|mixed|unknown|n/a> | モノレポ: <yes|no|n/a> | ArkGate: <none|detected> | スラッグ: <slug|n/a>
integrateの場合、非書き込みをリストします（モノレポルートインデックスのみの場合はパッケージ非書き込みを含む）。auditの場合、マトリックスパスと主要な矛盾をリストします。from-zero + サンドボックスの場合、昇格計画を含めます。planまたはfeatureの場合、パス + デフォルトの非書き込みをリストします。ArkGateブリッジの場合、シグナルとポストゲート同期 vs 監査強化をリストします。プロジェクトレベルの場合、スタックおよびモノレポを発見結果から含めます。
推奨レイアウト
project-root/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 チームガバナンス（オプション）
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # 意図 audit（オプション）
│ └── claims-matrix.md # 生きた主張 v0 カラム
├── adr/ # パッケージ / プロジェクト ADR（オプション）
├── plans/<slug>/ # v1.3 計画モード（コード前 / エピック）
│ └── README.md
├── decisions/
└── features/<slug>/ # コードバックアップ機能パック
補助ドキュメントは正当な理由がある場合のみ作成します（from-zeroを除く。この場合、完全な最小限のコアセットを作成する場合があります）。
成果物マトリックス（概要）
| 成果物 | from-zero / bootstrap | integrate (mature) | audit | plan | feature | sync |
|---|---|---|---|---|---|---|
| ハブ | 作成 | 拡張 / インデックス | オプションでステータス更新 | Plansをリンク | リンク | 必要に応じて |
| コアナラティブドキュメント | はい | 書き換えない | いいえ（読み取り専用） | いいえ | いいえ | 影響がある場合 |
| カバレッジマトリックス | はい | 必須 | インベントリの一部 | オプション行 | 行 | 更新 |
| 主張マトリックス | オプション事前 | ドリフトがある場合推奨 | 必須 | n/a | 監査がある場合スコープ | ドリフトがある場合 |
計画 docs/plans/ | n/a | n/a | n/a | 必須 | 存在する場合はリンク | 影響がある場合 |
| 機能パック | 主要ドメイン | ギャップ / エントリ | いいえ（要求がない限り） | いいえ（昇格まで） | 必須 | 影響がある場合 |
チーム docs/team/ | オーナーが既知の場合 | 要求された場合に作成/リンク | いいえ | n/a | n/a | 影響がある場合 |
| 並列完全ツリー | サンドボックスOK | ルートでは禁止 | n/a | n/a | n/a | n/a |
ワークフロー（全モード）
- ステップ0 — スコープ、モード、意図（プロジェクトの場合）、成熟度/バリアント、Out、スラッグ。関連する場合、ArkGateシグナルを検出。プロジェクト作業の場合、スタックおよびモノレポを検出（skill-discovery.md 多言語 + モノレポハブ）。
- まずコードを発見 — スタック認識インベントリ。モノレポの場合、パッケージインデックス + パッケージごとのインベントリ。ツリー、マニフェスト、エントリポイント、サンプルテスト。次にドキュメント（ある場合）。名前付き機能の場合、まずその表面を検索。Arkが検出された場合、arkgate-bridge.md に従ってインベントリを強化。
- 監査の場合、またはドキュメントが存在し意図が integrate/from-zero でドリフトが疑われる場合：調整を実行（modes.md § 監査、audit-template.md）。ポストゲート → ブリッジハンドオフ（modes.md §9）。
- ファイルを計画 — 作成/更新 および 非書き込み（機能/計画のデフォルト）。