プロジェクト初期設定

← ガイド目次

新規リポジトリに docs-kit を導入し、最初の 1 本を current にするまでを通しで説明する。所要 15 分程度。

既に設計書がある場合は 既存プロジェクトへの導入 を先に読む。

前提

• インストール が済んでいる (docs-kit --version が動く)
• 対象が git リポジトリで、コミットが 1 つ以上ある

全体の流れ

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

リポジトリのルートで実行する。

docs-kit init

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

生成されるもの:

init は冪等。 何度実行しても既存ファイルは壊れない。CLAUDE.md も <!-- docs-kit:begin v1 --> 〜 <!-- docs-kit:end --> の範囲だけを置換し、ブロック外の記述には一切触れない。バージョンアップ後に管理ブロックを更新したいときは init を再実行する。

git リポジトリ外で実行すると exit 3 で失敗する。

Step 2 — docs.config.yaml をリポジトリに合わせる

生成された既定値はこう。

schemaVersion: 1
root: docs
codeRoots: [src]
ignore: []

ここで直すのは codeRoots と ignore の 2 つだけ。 残りは基本的に触らない。

codeRoots — コードが置かれているトップレベルのディレクトリ群。scope がここから外れていると lint 警告 W003 が出る (タイポ検出のため)。実態に合わせる。

codeRoots: [cmd, internal, pkg]   # Go
codeRoots: [src, app]             # TypeScript
codeRoots: [lib, app]             # Ruby / Rails

ignore — 変わっても文書を stale にしたくないファイル。テストコードは必ず入れる。 ここを空のままにすると、テストを 1 行直すたびに設計書が stale になって運用が破綻する。

ignore:
  - "**/*_test.go"          # Go
  - "**/*.test.ts"          # TypeScript
  - "**/*.spec.ts"
  - "**/__snapshots__/**"
  - "**/testdata/**"
  - "**/fixtures/**"

ignore は scope に一致した後に適用される。「scope には含まれるが、変わっても仕様には影響しない」ものを書く場所。

設定はこの 4 キーで全部。層構造も status の値も INDEX の形式も設定不可。どのリポジトリでも AI の読み方を同じにするため。

Step 3 — 最初の ADR を書く

最初の 1 本は ADR にするのがよい。プロジェクトで既に決まっていること (言語の選択、フレームワーク、データストア等) を 1 つ選んで書く。

docs-kit new adr use-postgres --title "永続化に PostgreSQL を使う"

created ADR-0001
docs/adr/0001-use-postgres.md

ADR 番号は既存の最大値 + 1 で自動採番される。最終行に作成パスが出るので、そのままエディタで開く。

雛形は「状況 / 決定 / 帰結」の 3 節になっている。

---
id: ADR-0001
title: 永続化に PostgreSQL を使う
status: draft
---

# ADR-0001: 永続化に PostgreSQL を使う

## Context

(why this decision became necessary)

## Decision

(what was decided, and how)

## Consequences

(what changes as a result. The trade-offs being accepted)

書くときのコツ:

• 「状況」には制約を書く。 何が問題だったか、何が選択肢だったか
• 「決定」は 1 文で言い切る。 迷いを残すと後から読む人 (と AI) が判断できない
• 「帰結」に採用しなかった案とその理由を残す。 これが ADR の一番の価値。無いと半年後に同じ議論をやり直す

書き終えたら status を draft から current に手で変更する。

status: current

scope を持たない文書は手で current にしてよい。 鮮度保証の対象外なので verify を通す意味がない。ADR の多くはこれに当たる。

Step 4 — 最初の spec を書いて scope を設定する

次は「いまどう動くか」を書く。既に実装されている機能を 1 つ選ぶ。

docs-kit new spec editing-model --title "編集モデル"

created SPEC-editing-model
docs/spec/editing-model.md

front matter の scope を、この文書が責任を持つコード範囲に書き換える。

---
id: SPEC-editing-model
title: 編集モデル
status: draft
scope:
  - src/core/editing/**
depends_on: [ADR-0001]
---

scope の決め方は「このファイルが変わったとき、この文書を読み直す必要があるか?」。あるなら含める。

• 広すぎる (src/**) → 何をしても stale になり、やがて誰も見なくなる
• 狭すぎる (1 ファイルだけ) → 隣が変わっても気づけない
• 目安は 1 文書 1 モジュール

本文を書くときのコツ:

• 1 段落目に「この文書は何か」を書く。 which や MCP が返す 200 文字の要約は、本文の最初の非見出し・非空段落から自動で導出される。ここが良いと、AI が「開くべきか」を正しく判断できる
• 経緯は書かず ADR にリンクする。spec には「いま何が正しいか」だけ

Step 5 — 実装と突き合わせて verify する

書いた spec を実際のコードと読み合わせる。ここが最も重要な工程で、docs-kit が保証するのは「この作業を最後にやった時点」だけ。作業そのものは人間か AI がやる。

一致していることを確認したら:

docs-kit verify SPEC-editing-model

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

これで verified_at に HEAD の SHA が入り、status が draft から current に昇格した。

---
id: SPEC-editing-model
title: 編集モデル
status: current
scope:
  - src/core/editing/**
depends_on: [ADR-0001]
verified_at: 8f3a1c2e0b7d4a91c3f6e2d8b5a704c1e9f3d602
---

verify が書き換えるのは front matter の該当行だけ。 YAML を再シリアライズしないので、コメントも x- フィールドも本文もバイト単位で保たれる。

scope 内に未コミット変更があると警告が出る。verify は HEAD 基準なので、その変更は「検証済み」に含まれない。先にコミットするのが正しい。

Step 6 — INDEX を生成してコミットする

docs-kit lint

lint: OK (2 documents)

docs-kit index

generated: docs/INDEX.md (2 documents)

docs-kit stale

ADR-0001            skipped  (no scope)
SPEC-editing-model  ok       (verified at 8f3a1c2)

ok 1 / stale 0 / broken 0 / skipped 1

3 つとも通ったらコミットする。

git add docs docs.config.yaml CLAUDE.md .github .claude && git commit -m "docs: docs-kit を導入し最初の ADR と spec を追加"

docs/INDEX.md は生成物。手で編集しない。 内容がずれたら docs-kit index で作り直す。CI の index --check が同期を守る (gofmt と同じ方式)。

Step 7 — CI を有効化する

init が .github/workflows/docs-kit.yml を生成済み。push すればそのまま動く。

中身で必ず確認すること:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # ← これが無いと全文書が broken になる

fetch-depth: 0 は必須。 stale は git 履歴を歩くので、shallow clone だと verified_at の SHA が見つからず、全文書が unknown-sha で broken になる。

DOCS_KIT_VERSION には init を実行したバイナリのバージョンが埋め込まれる。ローカルビルドの場合は dev などになるので、実在するタグに書き換える。

env:
  DOCS_KIT_VERSION: v1.0.0

Step 8 — Claude Code に繋ぐ

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

これで AI 側から 4 つのツール (docs_which / docs_stale / docs_verify / docs_new) が使える。init が CLAUDE.md に入れた管理ブロックが、AI 側の作業手順を固定する。

.claude/commands/ に置かれた 2 つのスラッシュコマンドも使えるようになる。

Step 9 — 一巡させて動作確認する

導入が効いているか、実際にループを 1 周させて確かめる。

1. 逆引きが効くか

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

primary:
  SPEC-editing-model  current  8f3a1c2  docs/spec/editing-model.md
related:
  ADR-0001            current  -        docs/adr/0001-use-postgres.md

primary に spec が出て、depends_on で繋いだ ADR が related に出れば正しい。

2. 鮮度判定が効くか

scope 内のファイルを適当に変更してコミットし、stale を実行する。

docs-kit stale

ADR-0001            skipped  (no scope)
SPEC-editing-model  stale    code-changed: 1 files changed since 8f3a1c2
  - src/core/editing/model.ts

ok 0 / stale 1 / broken 0 / skipped 1

stale が出れば成功。文書を実装に合わせて更新し、docs-kit verify SPEC-editing-model で ok に戻す。

ここまで通れば導入完了。あとは ワークフロー のループを回すだけ。

つまずきやすい点

次に読む

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