Claude Code

Claude Code（Claude CLI）でのドキュメント管理

ドキュメントは「書くこと」より「コードと同期させ続けること」が難しい資産です。Claude Code（Claude CLI）は、CLAUDE.md による文脈管理から、コードを根拠にしたドキュメント生成、Hook による自動更新まで、その課題に答える手段を備えています。海外ブログの調査をもとに整理します。

本記事は、英語圏の公式ドキュメント・技術ブログを当社が調査し、要点を日本語でまとめたものです。各手法の出典は記事末尾の「参考元記事」に記載しています。詳細は必ず元記事をご確認ください。

2層のメモリ：人が書く CLAUDE.md と Claude が書く自動メモリ

Claude Code のドキュメント基盤は、書き手によって2層に分かれます（元記事1）。

種類書き手内容
CLAUDE.mdあなた（人間）コーディング規約・ワークフロー・アーキテクチャなど、伝えたい指示
自動メモリ（MEMORY.md）Claude 自身発見したビルドコマンドやデバッグの知見などのメモ

自動メモリは MEMORY.md の冒頭（約200行 / 25KB）が毎回読み込まれ、より深い内容は debugging.md や api-conventions.md といったトピック別ファイルに分けて必要時に参照されます。# コマンドで追記、/memory で読み込み中のファイルを監査できます（元記事1）。

/init は出発点であって完成形ではない

すべての情報源が、/init を CLAUDE.md 生成の出発点として扱います。/init は「パッケージファイル、既存ドキュメント、設定ファイル、コード構造」を解析してプロジェクトに合った初期設定を作ります。既存ファイルがある場合は上書きせず改善を提案します（元記事1・3）。Sid Bharath 氏は「/init はプロジェクト全体を見て Claude.md を作る。これがプロジェクトの記憶になる」と表現します（元記事5）。

CLAUDE.md は短く・具体的に・剪定する

公式は明確な「含める / 含めない」の基準を示しています（元記事2）。

判断基準は「この行を消したら Claude がミスをするか？ しないなら削る」。詳細はトピック別ファイルや .claude/rules/*.md（YAML の paths: で対象パス指定）に分け、@README や @package.json などの @path インポートで重複を避けます（元記事1・2）。階層配置（グローバル / プロジェクト / フロント / バック）では「より具体的なファイルが一般的なものを上書き」します（元記事5）。

注意： 公式は「肥大化した CLAUDE.md は、実際の指示を Claude に無視させる原因になる」と繰り返し警告しています。遵守させたい重要事項には「IMPORTANT」「YOU MUST」を控えめに付与すると効果的です（元記事2）。

ドキュメントは「記憶」ではなく「コード」から生成する

もっとも重要な原則が、ドキュメントをコードから導出することです。Developer Toolkit の解説では、次のような具体的プロンプトが示されています（元記事6）。

src/services/ の全ファイルを読み、エクスポートされた関数・クラス・型すべてに JSDoc コメントを追加して

同期維持は Hook と CI で「決定論的」に

ドキュメントが陳腐化する最大の原因は、更新が人間（やモデル）の善意に依存することです。これをHook と CI で自動化します。

Hook が好まれるのは、助言的な CLAUDE.md と違って必ず発火するからです。

ドキュメントがオンボーディングと調査を加速する

整備されたドキュメントは、そのままチームの生産性に直結します。Anthropic 社内では、セキュリティチームが「複数のドキュメントソースを取り込んで Markdown のランブックを作成」し、データチームはコードベースを渡すだけで「CLAUDE.md を読み、依存関係を特定し、データパイプラインの連携を説明」させています。推論チームでは、モデル固有のドキュメント取り込みにより「通常1時間の Google 検索が10〜20分で済む」といいます（元記事4）。

当社の視点： ハシトシステムは、ドキュメントを「コードと同じリポジトリで、コードから生成し、CI で鮮度を検証する」 docs-as-code の運用を重視しています。Claude Code はこの運用を現実的なコストで回せるようにします。仕様書・設計書の整備や同期の自動化はお問い合わせよりご相談ください。

よくある質問（FAQ）

Claude Code のメモリは何層に分かれていますか？

書き手によって2層に分かれます。1つは人間が書く CLAUDE.md で、コーディング規約・ワークフロー・アーキテクチャなど伝えたい指示を記述します。もう1つは Claude 自身が書く自動メモリ（MEMORY.md）で、発見したビルドコマンドやデバッグの知見などのメモが残ります。自動メモリは冒頭（約200行 / 25KB）が毎回読み込まれ、より深い内容は debugging.md や api-conventions.md などトピック別ファイルに分けて必要時に参照されます。

/init を実行すれば CLAUDE.md は完成しますか？

/init は出発点であって完成形ではありません。/init はパッケージファイル、既存ドキュメント、設定ファイル、コード構造を解析してプロジェクトに合った初期設定を作り、既存ファイルがある場合は上書きせず改善を提案します。その後は短く・具体的に保ち、「この行を消したら Claude がミスをするか。しないなら削る」という基準で剪定し、詳細はトピック別ファイルや @path インポートで参照して育てていきます。

ドキュメントをコードと同期させ続けるには？

もっとも重要な原則は、ドキュメントを記憶ではなくコードから生成することです。JSDoc は実際の TypeScript の型から、OpenAPI は Zod スキーマから導出します。そのうえで、ルートファイル変更時に OpenAPI 更新を促す PostToolUse Hook や、スペックと実際のルートハンドラを比較する CI フレッシュネスチェックで、同期維持を決定論的に自動化します。Hook が好まれるのは、助言的な CLAUDE.md と違って必ず発火するからです。

参考元記事

  1. Anthropic「Manage Claude's memory（CLAUDE.md & memory）」(公式ドキュメント) — https://code.claude.com/docs/en/memory
  2. Anthropic「Best practices for Claude Code」(公式ドキュメント) — https://code.claude.com/docs/en/best-practices
  3. Anthropic「Using CLAUDE.md files: Customizing Claude Code for your codebase」(2025年11月25日) — https://claude.com/blog/using-claude-md-files
  4. Anthropic「How Anthropic Teams Use Claude Code」(2025年7月24日) — https://claude.com/blog/how-anthropic-teams-use-claude-code
  5. Sid Bharath「Cooking with Claude Code: The Complete Tutorial & Guide」(2025年7月8日、2026年4月更新) — https://sidbharath.com/blog/claude-code-the-complete-guide/
  6. Developer Toolkit「Documentation Generation with Claude Code」(2026年6月) — https://developertoolkit.ai/en/claude-code/lessons/documentation/
← 技術ブログ一覧へ戻る