インストール

配布物は noop.co.jp から直接ダウンロードする。パッケージマネージャへの登録はしていない。

動作要件


OS	macOS / Linux / Windows
アーキテクチャ	amd64 / arm64 (Windows arm64 は配布対象外)
必須	`git` — read-only でシェルアウトする。PATH 上にあること
ランタイム	不要。CGO 無効の静的バイナリ

git 以外の外部コマンドには依存しない。docs-kit がリポジトリに書き込むのは docs/ 配下・docs.config.yaml・CLAUDE.md の管理ブロック・生成した CI と .claude/commands だけで、git 操作 (commit / push 等) は一切行わない。

1. バイナリでインストール

macOS / Linux

curl -fsSL "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar -xz && sudo install -m 755 docs-kit /usr/local/bin/

uname の結果から配布物名を組み立てている。中身を確認してから実行したい場合は分けて実行する。

echo "docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz"

curl -fLO "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_darwin_arm64.tar.gz"

tar -xzf docs-kit_darwin_arm64.tar.gz && sudo install -m 755 docs-kit /usr/local/bin/

アーカイブの中身はバイナリ docs-kit と LICENSE / NOTICE / README.md の 4 ファイル。docs-kit は Apache-2.0 なので、再配布物に NOTICE が付いて回る必要がある (第 4 条 d)。PATH に入れるのはバイナリだけでよい。

配布物の一覧:

OS	アーキテクチャ	ファイル名
macOS	Apple Silicon	`docs-kit_darwin_arm64.tar.gz`
macOS	Intel	`docs-kit_darwin_amd64.tar.gz`
Linux	x86_64	`docs-kit_linux_amd64.tar.gz`
Linux	ARM64	`docs-kit_linux_arm64.tar.gz`
Windows	x86_64	`docs-kit_windows_amd64.zip`

バージョンを指定する

latest/ は常に最新版を指す。特定のバージョンが欲しい場合はバージョン番号をパスに入れる。こちらは一度公開したら中身が変わらない。

curl -fLO "https://downloads.noop.co.jp/docs-kit/v1.1.0/docs-kit_darwin_arm64.tar.gz"

チェックサム

同じディレクトリの checksums.txt に SHA-256 がある。

curl -fLO "https://downloads.noop.co.jp/docs-kit/latest/checksums.txt" && shasum -a 256 -c checksums.txt --ignore-missing

Windows

docs-kit_windows_amd64.zip をダウンロードし、展開した docs-kit.exe を PATH の通ったディレクトリに置く。

curl.exe -fLO "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_windows_amd64.zip"
mkdir $env:USERPROFILE\bin -Force
Expand-Archive docs-kit_windows_amd64.zip -DestinationPath $env:USERPROFILE\bin -Force
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")

macOS の Gatekeeper

署名なしバイナリのため、初回実行時にブロックされることがある。

xattr -d com.apple.quarantine /usr/local/bin/docs-kit

2. 動作確認

docs-kit --version

docs-kit v1.1.0

docs-kit --help

docs-kit — a design-doc management tool for AI-assisted coding

Usage: docs-kit [-C <dir>] <command> [flags] [args]

Commands:
  init                Generate scaffolding + config + CLAUDE.md block + CI
  adopt               Add front matter stubs to existing docs (status: draft)
  lint                Validate front matter against the schema (exit 1 = errors)
  stale [id...]       Freshness check (exit 0=ok / 1=stale / 2=broken)
  index [--check]     Generate INDEX.md (--check verifies sync, for CI)
  which <path...>     Reverse lookup: path -> related documents
  new <layer> <slug>  Create a document from a template (--title)
  schema              Print the front matter schema (fields / enum / per-layer rules)
  verify <id...>      Update verified_at to HEAD and promote to current
  mcp                 Start the MCP server over stdio (docs_which / docs_stale / docs_verify / docs_new)

Flags:
  -C <dir>            Change the working directory (as git does)
  --format text|json  Output format for lint / stale / which / schema
  --version           Print the version

CLI のメッセージと --help は英語。

ここまで動けばインストールは完了。次はプロジェクト初期設定へ。

3. アップグレードとアンインストール

アップグレード — インストール時と同じ手順を再実行してバイナリを上書きするだけ。設定ファイルや文書の移行は不要。

curl -fsSL "https://downloads.noop.co.jp/docs-kit/latest/docs-kit_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar -xz && sudo install -m 755 docs-kit /usr/local/bin/

アップグレード後、CLAUDE.md の管理ブロックを最新仕様に合わせたい場合は各リポジトリで docs-kit init を再実行する (冪等。管理ブロック以外は上書きされない)。

アンインストール — バイナリを消すだけ。

sudo rm /usr/local/bin/docs-kit

docs/ も docs.config.yaml もただの Markdown と YAML なので、そのまま残しておける。

4. CI にインストールする

docs-kit init を実行すると .github/workflows/docs-kit.yml が生成され、そこにインストール手順が含まれる。手で書く場合はこう。

- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # stale は全履歴を必要とする。必須
- name: Install docs-kit
  run: |
    curl -fsSL "https://downloads.noop.co.jp/docs-kit/${DOCS_KIT_VERSION}/docs-kit_linux_amd64.tar.gz" | tar -xz
    sudo install -m 755 docs-kit /usr/local/bin/docs-kit
  env:
    DOCS_KIT_VERSION: v1.1.0
- run: docs-kit lint
- run: docs-kit stale
- run: docs-kit index --check

押さえるべき点が 2 つある。

fetch-depth: 0 は必須。 shallow clone では verified_at の SHA が履歴に存在せず、全文書が broken (unknown-sha) になる
バージョンを固定する。 latest/ ではなく v1.1.0/ のようにバージョン付きのパスを指定しておくと、リリースのたびに CI の挙動が変わることを防げる

5. Claude Code に MCP サーバとして登録する

CLI だけでも完結するが、AI から直接使えるようにすると効果が大きく変わる。

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

この登録は PATH 上の docs-kit を指す。 そのためバイナリを差し替えても再登録は不要で、セッションを開き直せば新しいツール定義がそのまま反映される。

登録の確認:

claude mcp list

セッション内で 4 つのツール (docs_which / docs_stale / docs_verify / docs_new) が見えていれば成功。

解除:

claude mcp remove docs-kit

単体で起動して確かめる

MCP サーバは stdio で動くので、通常は手で起動しない。ただし起動前に config と git を検査して、不正なら即座に exit 3 で終了する設計になっているので、疎通確認には使える。

docs-kit mcp

すぐ落ちるならリポジトリ側の問題 (config が無い / git リポジトリでない等)。何も出力せず待ち受けたら正常なので、Ctrl-C で止める。

stdin / stdout は MCP の通信路として占有される。ログはすべて stderr に 1 呼び出し 1 行の JSON で出る。

6. うまくいかないとき

症状	原因と対処
`docs-kit: command not found`	PATH が通っていない。`which docs-kit` で確認する。`/usr/local/bin` 以外に置いたなら、そのディレクトリを PATH に追加する
ダウンロードが 404 になる	ファイル名が違う。上の配布物一覧と照合する。Windows arm64 は配布していない
`cannot execute binary file`	OS / アーキテクチャ違いを取得している。`uname -sm` の結果とファイル名を突き合わせる
macOS で「開発元を検証できません」	`xattr -d com.apple.quarantine /usr/local/bin/docs-kit`
`docs.config.yaml が見つかりません` (exit 3)	そのリポジトリでまだ `docs-kit init` を実行していない。プロジェクト初期設定へ
`git リポジトリではありません` (exit 3)	git 管理下のディレクトリで実行する。`-C <dir>` で対象を指定することもできる
CI で全文書が `broken` になる	`fetch-depth: 0` が抜けている
Claude Code にツールが出てこない	`claude mcp list` で登録を確認。サーバプロセスは PATH 上の `docs-kit` を起動するので、Claude Code から見える PATH に入っている必要がある

次に読む

プロジェクト初期設定 — 新規リポジトリに導入する
既存プロジェクトへの導入 — 既にある Markdown を取り込む