既存プロジェクトへの導入

← ガイド目次

既に設計書がある (かもしれない) リポジトリに docs-kit を後から入れる手順。新規リポジトリなら プロジェクト初期設定 のほうが早い。

導入の考え方 — 一気に current にしない

既存文書を導入するときの最大の失敗は、全文書をいきなり current にしてしまうこと。

current は「実装と突き合わせ済み」という宣言。突き合わせていない文書を current にすると、docs-kit が保証しているのは形式だけになり、AI は古い内容を仕様として信じ続ける。docs-kit を入れる前より状況が悪化する。

そのため docs-kit adopt は必ず status: draft で取り込む。draft は「参考情報。実装コードを正とする」という意味なので、取り込んだ直後は何も保証していない状態が正しく表現されている。

draft のまま放置しても害はない。 焦って昇格させるより、価値のある文書から 1 本ずつ current にしていくほうが速く落ち着く。

全体の流れ

Step 0 — 現状の棚卸し

まず、いま何がどこにあるかを一覧にする。

find . -name '*.md' -not -path './node_modules/*' -not -path './.git/*'

出てきた文書を 3 つに仕分ける。

この時点で「捨てる」の判断を済ませておく。 取り込んでから整理しようとすると、draft の山に埋もれて手が付かなくなる。

どの層に置くかの判断は ワークフロー の判断フローに従う。ざっくりは:

Step 1 — docs-kit init で足場を作る

docs-kit init

既存ファイルは上書きされないので、既に docs/ があっても安全。

created: docs.config.yaml
skipped: docs/adr/
created: docs/spec/
created: docs/arch/
created: docs/plan/
created: docs/INDEX.md
updated: CLAUDE.md
created: .github/workflows/docs-kit.yml
created: .claude/commands/docs-verify.md
created: .claude/commands/docs-catchup.md

CLAUDE.md が既にある場合は、<!-- docs-kit:begin v1 --> ブロックが末尾に追記されるだけ。既存の記述には触れない。

続けて docs.config.yaml を実態に合わせる。

schemaVersion: 1
root: docs                 # 文書のルート。docs/ 以外に置いているなら変える
codeRoots: [src, app]      # コードのトップレベルディレクトリ
ignore:                    # 変わっても stale にしたくないファイル
  - "**/*.test.ts"
  - "**/__snapshots__/**"
  - "**/fixtures/**"

ignore にテストを入れ忘れない。 既存プロジェクトはテストが多いので、ここが空だと導入直後から全文書が stale になる。

文書が docs/ 以外にある場合

root を変えれば documentation/ でも design/ でも構わない。

root: documentation

ただしその下に adr/ spec/ arch/ plan/ の 4 層が必要なのは変わらない。層の名前は設定できない。

Step 2 — 既存文書を 4 層に振り分ける

docs-kit adopt が見るのは <root>/<layer>/ 直下の *.md だけ。 サブディレクトリは走査されないので、先に移動しておく必要がある。

ファイル名の規則に合わせる

slug は [a-z0-9]+(-[a-z0-9]+)* — 小文字英数とハイフンのみ。スペース、大文字、アンダースコア、日本語のファイル名はすべて対象外になる。

git mv docs/design/EditingModel.md docs/spec/editing-model.md

git mv docs/decisions/adr-3-undo.md docs/adr/0003-undo-stack.md

ADR は 4 桁ゼロ埋めにする (3-undo.md ではなく 0003-undo.md)。既存の採番が飛んでいても構わないが、重複だけは潰す。

リネームは git mv で行う。履歴が繋がっていると、後の鮮度判定で純リネームとして扱われる余地が残る。

資産ファイルはサブディレクトリへ

画像などは層ディレクトリの直下に置かず、サブディレクトリに逃がす。サブディレクトリは走査対象外なので、そのまま置いておける。

docs/
├── spec/
│   └── editing-model.md
└── assets/                ← 走査されない
    └── editing-model.png

Step 3 — docs-kit adopt で front matter を付与する

docs-kit adopt

adopted: docs/adr/0003-undo-stack.md (id: ADR-0003, status: draft)
adopted: docs/spec/editing-model.md (id: SPEC-editing-model, status: draft)
adopted: docs/arch/overview.md (id: ARCH-overview, status: draft)
skipped: docs/spec/Editing Model.md (the filename does not match the naming rules; rename it or recreate it with docs-kit new)
adopt: 3 adopted, 1 skipped

各ファイルの先頭にスタブが挿入される。

---
id: SPEC-editing-model
title: 編集モデル
status: draft
---

• id はファイル名から導出
• title は本文の最初の # 見出し。無ければファイル名
• status は必ず draft 固定

adopt が触らないもの

冪等なので、リネームして再実行、を繰り返してよい。スキップされたファイルを直しては adopt を打つ、というループで潰していける。

Step 4 — lint を通す

docs-kit lint

docs/adr/0007-caching.md:E004 id "ADR-0007" and filename "0007-caching.md" do not correspond (expected ADR-0007)
docs/spec/api.md:E011 referenced id "ADR-0099" does not exist
docs/spec/legacy.md:W003 scope "vendor/**" points outside codeRoots [src] (warning)

エラー (E) は必ず潰す。警告 (W) は exit 0 なので後回しでよい。

W002 (scope が 1 件も一致しない) がここに出ないのは、adopt が全文書を draft にするため。draft は W002 の対象外で、verify で昇格させた文書から順に効き始める。

導入直後によく出るもの:

E007 は既存文書でよく踏む。 元々 author: や updated: を書いていた場合、x-author: x-updated: にすればそのまま保持される (ツールは解釈せず持つだけ)。

docs-kit index && git add -A && git commit -m "docs: 既存設計書を docs-kit の管理下に取り込む (draft)"

ここでいったんコミットする。 この時点で全文書が draft なので、stale は全件 skipped になり CI も通る。

Step 5 — 1 本ずつ current に昇格させる

ここからが本番。全部やろうとせず、価値の高いものから 1 本ずつ進める。

優先順位

1. AI が頻繁に触るモジュールの spec — 効果が最も大きい
2. arch/overview.md — 全体像は最初に信頼できる状態にしたい
3. まだ有効な ADR — scope が無いので手で current にするだけ (コストが低い)
4. その他の spec

1 本あたりの手順

具体的には front matter に scope を足して、

---
id: SPEC-editing-model
title: 編集モデル
status: draft
scope:
  - src/core/editing/**
---

本文を実装と読み合わせて直したら:

docs-kit verify SPEC-editing-model

SPEC-editing-model: verified_at → 8f3a1c2 (promoted to current)

昇格させないという選択

全文書を current にする必要はない。

• 内容が古すぎて直す価値が無い → 削除する。git 履歴には残る
• 後継の文書がある → status: superseded + superseded_by: SPEC-xxx を付ける
• 参考情報としては使える → draft のまま置いておく。AI は参考として扱う

draft のまま残すのは正当な選択。 「何も保証していない」と正しく表明できている状態なので、無理に昇格させて嘘の current を作るより遥かによい。

AI に任せる

Claude Code を繋いでいれば、この工程は /docs-catchup である程度まとめて進められる。文書ごとに「実装と突き合わせて、一致していれば verify、ずれていれば直してから verify」を回してくれる。ただし scope を書くのと、最終的な判断は人間がやるほうがよい。

Step 6 — CI を段階的に厳しくする

導入直後にいきなり 3 コマンド全部を必須にすると、stale で真っ赤になって誰も見なくなる。段階を踏む。

第 1 段階 — lint だけ必須にする

- run: docs-kit lint
- run: docs-kit index --check

形式の破綻だけを止める。全文書が draft なので stale は常に通る。

第 2 段階 — stale を警告として回す

- run: docs-kit stale || true

落とさずに結果だけ見る。current にした文書が増えるにつれ、判定が意味を持ちはじめる。

第 3 段階 — stale も必須にする

- run: docs-kit lint
- run: docs-kit stale
- run: docs-kit index --check

current の文書がひととおり揃ったらここへ移行する。以降は「実装を変えたら該当文書を verify する」が強制される。

どの段階でも fetch-depth: 0 は必須。

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Step 7 — Claude Code に繋ぐ

claude mcp add docs-kit -- docs-kit mcp

既存プロジェクトでは、繋いだ直後の効果が特に分かりやすい。

docs-kit which src/core/editing/model.ts

primary:
  SPEC-editing-model  current  8f3a1c2  docs/spec/editing-model.md
related:
  ADR-0003            current  -        docs/adr/0003-undo-stack.md

docs/ に 50 本の文書があっても、AI が読むのはここに出た数本だけになる。

ケース別の対処

モノレポ

config はリポジトリルートに 1 本だけ。 サブディレクトリごとに docs.config.yaml を置くことはできない。

root: docs                          # リポジトリ全体で 1 つの docs/
codeRoots: [packages, apps]

パッケージごとの文書は slug で名前空間を切る。

docs/spec/
├── web-editing-model.md      → SPEC-web-editing-model
├── api-auth.md               → SPEC-api-auth
└── worker-queue.md           → SPEC-worker-queue

scope はパッケージのパスを指す。

scope:
  - packages/web/src/editing/**

文書が多すぎて手が回らない

全部 draft で取り込んだまま止めてよい。 その状態でも、

• which の逆引きは効く (draft でも返る)
• AI は draft を「参考情報」として正しく扱う
• CI は lint と index --check だけで回る

現在の運用より悪くなることはない。current 化は必要になったモジュールから進める。

文書に進行状態が書かれている

「Phase 1: 完了 ✅」のようなチェックリストが混ざっているなら、設計書からは外して Issue へ移す。 進行状態が混ざると、文書を読むたびに「これは仕様か進捗か」の判別が必要になり、AI も人間も間違える。

作業計画そのものは plan/ に置けるが、plan は使い捨てでマージ時に削除する前提。恒久的なタスク管理には使わない。

既存の front matter が別のスキーマで入っている

静的サイトジェネレータ用の front matter (layout: date: tags: 等) が既に付いている場合、adopt はそのファイルをスキップする (front matter がある扱いになるため)。

必要なフィールドを手で足し、docs-kit が知らないキーには x- を付ける。

---
id: SPEC-editing-model     # 追加
title: 編集モデル           # 既存の title を流用できる
status: draft              # 追加
x-layout: doc              # layout: → x-layout:
x-date: 2025-04-01         # date: → x-date:
x-tags: [editor]           # tags: → x-tags:
---

x- フィールドはツールが解釈せず、そのまま保持する。verify も行単位で書き換えるので壊れない。

GitHub Wiki やドキュメントサイトに置いている

docs-kit が扱えるのは同じリポジトリ内の Markdown だけ。鮮度判定が git 履歴に依存しているため、別リポジトリや外部サービスにある文書は対象にできない。

取り込むなら、設計書としての実体をリポジトリ内に移す。ユーザー向けドキュメントは対象外なので、そのまま外に置いておけばよい。

導入できたかの確認

docs-kit lint && docs-kit stale && docs-kit index --check

3 つとも通り、かつ current の文書が 1 本以上あること。current が 0 本だと形式が整っただけで、鮮度の保証はまだ何も働いていない。

docs-kit stale

ADR-0003            skipped  (no scope)
ARCH-overview       ok       (verified at 8f3a1c2)
SPEC-editing-model  ok       (verified at 8f3a1c2)
SPEC-legacy-api     skipped  (draft)

ok 2 / stale 0 / broken 0 / skipped 2

この形になれば導入完了。あとは ワークフロー のループを回しながら、skipped を少しずつ減らしていく。

次に読む

• ドキュメント管理ワークフロー — 日々の運用の全体像
• コンセプトと設計思想 — なぜ draft から始めるのか