Skill v1.0.0

currentAutomated scan100/100

tdyzzsp47/claude-skills/documentation

──Details

PublishedSeptember 27, 2026 at 10:14 AM

Content Hashsha256:3101940121f69990...

Git SHAe0a42cc77560

──Files

Files (1 file, 9.1 KB)

SKILL.md9.1 KBactive

SKILL.md · 181 lines · 9.1 KB

version: "1.0.0" name: documentation description: README・CLAUDE.md・設計書・ランブック等の技術文書を作成・更新・鮮度管理するスキル。新機能追加時・新規参加者対応時・既存文書の陳腐化を検出したい時に使う。

ドキュメンテーション

目的

「コードで分からないこと」を伝える。実装の背景・設計判断の理由・制約・運用手順など、コードを読んでも分からない情報を文書化し、チームの認知負荷を下げる。コードで分かることは書かない。

使うタイミング

新機能・新サービスを作ったのにREADMEが追いついていない
新規参加者がセットアップに詰まっている
エージェントがプロジェクト固有の規約を把握できていない(CLAUDE.md未整備)
設計判断の理由が誰も分からなくなっている(ADR未記録)
障害対応手順が口頭伝承になっている
四半期棚卸しで陳腐化した文書を発見した

ドキュメントの種類と置き場所

種類	対象読者	置き場所	更新タイミング	関連スキル
README	新規参加者・外部利用者	リポジトリルート	機能追加・破壊的変更時	—
CLAUDE.md	AIエージェント	リポジトリルート・各サブディレクトリ	規約・コマンド変更時	—
ADR(Architecture Decision Record)	設計者・将来の自分	`docs/adr/`	重要な設計判断時	[[architecture-design]]
API文書	API利用者	`docs/api/` またはスキーマから自動生成	スキーマ変更時	[[api-design]]
ランブック	運用者・オンコール担当	`docs/runbook/`	障害対応後・手順変更時	[[monitoring-operations]]
CHANGELOG	利用者・リリース管理者	リポジトリルート	リリース時	[[cicd-deployment]]
設計書・詳細設計	開発者	`docs/design/`	設計変更時	[[detailed-design]]

正本はリポジトリに置く。 WikiやNotionを正本にするとコード変更と文書更新が乖離する。

進め方

読者を決める: 誰のために書くかを最初に明記する。新規参加者・運用者・API利用者・未来の自分——読者が曖昧なドキュメントは書けない
書くべき内容を絞る: コードを読めば分かることは書かない。「なぜその設計にしたか」「どの制約があるか」「何をやってはいけないか」を優先する
既存の文書を確認する: 重複・矛盾・正本の所在を整理してから書き始める
テキストベースで書く: 図はMermaid等のテキスト形式を使う。diffが見え、エージェントが編集でき、レビューができる
セットアップ手順を検証する: 新人または新しい環境で実際に手順通りに動かして確認する。動かない手順書は害になる
コードの近くに置く: 関連するコードと同一リポジトリ・同一PRで更新する運用を徹底する
陳腐化したものは「直すか消す」: 間違ったドキュメントはゼロより害。四半期に一度の棚卸しで削除も選択肢に入れる

成果物テンプレート

READMEテンプレート

markdown

# プロジェクト名
 
一言で何ができるか。誰のどんな問題を解決するか。（3行以内）
 
## セットアップ
 
\`\`\`bash
# コピペで動く手順のみ記載
git clone https://github.com/org/repo.git
cd repo
cp .env.example .env        # 環境変数の設定が必要な場合
npm install
npm run dev
\`\`\`
 
動作確認: http://localhost:3000 にアクセスして「〇〇」が表示されれば成功。
 
## 使い方
 
\`\`\`bash
# 基本的なコマンドや操作の例
npm run build
npm start
\`\`\`
 
詳細は [docs/](docs/) を参照。
 
## 開発参加
 
\`\`\`bash
npm test       # テスト実行
npm run lint   # リントチェック
\`\`\`
 
-ブランチ戦略: `main` は常にデプロイ可能。機能開発は `feature/xxx` ブランチで行う
-PRのサイズは400行以内を目安。コミットメッセージは [Conventional Commits](https://www.conventionalcommits.org/) に従う
 
## ライセンス
MIT

CLAUDE.mdテンプレート

markdown

# CLAUDE.md
 
このファイルはAIエージェントが毎回参照する前提で書いている。簡潔に。
 
## ビルド・テストコマンド
 
\`\`\`bash
npm run dev        # 開発サーバー起動
npm test           # 全テスト実行
npm run test:unit  # ユニットテストのみ
npm run lint && npm run build  # リント + 本番ビルド
\`\`\`
 
## ディレクトリ構成
 
\`\`\`
src/
  api/        # APIルート定義(Express)
  domain/     # ビジネスロジック。フレームワーク依存なし
  infra/      # DB・外部APIなどの実装詳細
  shared/     # 複数レイヤーで使う型・ユーティリティ
docs/
  adr/        # アーキテクチャ決定記録
  runbook/    # 障害対応手順
\`\`\`
 
## コード規約
 
-TypeScript strict モード。`any` は原則禁止
-テストファイルは対象ファイルと同ディレクトリに `*.test.ts` で置く
-環境変数は `src/config.ts` 経由でのみアクセスする
 
## やってはいけないこと
 
-`main` ブランチへの直接pushは禁止
-本番DBへの直接接続は禁止(ステージング環境を使う)
-シークレットをコードにハードコードしない
 
## 主要な設計判断(背景)
 
-ドメインレイヤーをフレームワーク非依存にした理由: テスト容易性とフレームワーク移行コストの低減
-ORMを使わずクエリビルダーを採用した理由: 複雑なクエリのパフォーマンスチューニングが必要なため

チェックリスト

[ ] 読者(誰が読むか)を冒頭または自分のメモで明確にしたか
[ ] コードを読めば分かる内容を省いたか
[ ] セットアップ手順を実際の環境で動作確認したか
[ ] 図はMermaid等のテキスト形式で書いたか
[ ] コード変更と同じPRでドキュメントを更新したか
[ ] 正本がリポジトリに存在し、WikiやNotionに分散していないか
[ ] 陳腐化した記述を削除または修正したか
[ ] CLAUDE.mdにビルド・テストコマンドと「やってはいけないこと」が揃っているか
[ ] ADRに「なぜその設計を選んだか」と「検討したが選ばなかった代替案」が記載されているか

アンチパターン

書いた直後から更新されない設計書: コードと別のPRで管理すると乖離する。コード変更と文書更新を同一PRにする運用が必要
Wiki・Notion・リポジトリに分散して正本不明: 「どれが最新か」の確認コストが発生する。正本はリポジトリに一本化する
コードのコメントと同じ内容の説明文: 二重管理になり片方が腐る。READMEには「なぜ」だけ書く
動かない手順書: セットアップ手順を一度も検証しないまま放置する。動かないREADMEはゼロより害になる
すべてを文書化しようとして力尽きる: 網羅性を目指すと更新が止まる。「新規参加者が詰まる箇所」に絞る
間違ったドキュメントを残す: 「後で直す」と放置した誤情報は混乱を招く。直せないなら削除する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	担当	具体的な使い方
司令塔(メインモデル)	何を文書化するかの判断・全体構成の設計	対象読者の確認、既存文書の重複・矛盾の洗い出し、各エージェントへの作業割り当てと最終レビュー
Opus相当	設計ドキュメント・ADRのレビューと品質担保	設計判断の妥当性・代替案の網羅性・背景情報の十分性を深く評価させる
Sonnet相当	ドキュメントのドラフト作成・更新・整形	READMEやCLAUDE.mdの初稿生成、既存文書への追記・修正、Mermaid図の生成
Haiku相当	陳腐化箇所の検出(コードとの突き合わせ)	コードとドキュメントを比較して「記述が古くなった箇所」「コマンドが変わった箇所」を高速にスキャンさせる