これまで /init したものに適当に書き足したものを CLAUDE.md や AGENTS.md として使ってきたが、いくつか記事を読んだり参考になる CLAUDE.md を見たりで整理したい気持ちになったので整理した。いくつか管理しているリポジトリに適用していきたかったので、 Claude Code の Plugin として skill にしている。
整理するにあたって、以下のことを意識して作るようにした:
- 最小限であること
- 現状を尊重すること
- リポジトリ単位では、人間がやってほしいワークフローを押し付けないこと
- 常に使うものでないなら、別ドキュメント / skills / slash command に切り出すこと
最終的に次のような構成になった:
このリポジトリの目的、アプリケーションの簡単な説明
## Architecture Overview
- どのように作られ、動いているかの概要を数行で書く
- 例えば Cloudflare Workers と KV を使って構築している
## Directory Structure
- よく触ることになるファイルのポインタ
## Core Principles
- 現状を尊重してほしいとか、一般的によいとされる開発をしてねとか、消すこともある
- リポジトリで特に重要なコーディング原則などがあれば書き足す
## Commands
- 普段使うコマンド
## Testing
- モックは最小限にしてほしいとか
- リポジトリで必要なことや方針があれば書き足す
## Language Policy
- AI 向けのドキュメントは英語で書いてほしい
- 他はユーザーに任せる
## Additional Resources
- 特に重要な ADR や ARCHITECURE.md へのリンクこれに加えて設計の記録である ADR 、全体の設計を詳しく書いた ARCHITECURE.md 、リポジトリごとの固有の BEST_PRACTICES.md をだいたいの場合で作るようにしている。要所で守ってほしいルールはだいたい skill 化していて、例えば ADR のフォーマットを skill にして書くときに読んでもらうようにしている。他には PR のフォーマットとかフロントエンドの実装ガイドラインなんかが便利。
これに加えて、言語の設定や推奨したいコーディング、ワークフローを書いた ~/.claude/CLAUDE.md を使っている。大した内容ではないが。
所感としては、これまで /init なりで作っていた比較的大きいものから移行しても大して困っていないので、これくらいで十分なんだなという肌感はある。 Core Principles にちょっと抽象的なことを書いているが効いているかよくわからない。Language Policy を書いたのが結構良くて、AI 向けのものをこれまで英語で書かれたり日本語で書かれたりしていたのがなくなった(元々が日本語ならそうなるが…)。
Refs
読んだ記事:
参考にさせていただいた CLAUDE.md とか: