はじめに
Claude Code を使ったプロジェクトでは、CLAUDE.md というファイルで Claude Code にプロジェクトの情報を伝えることができます。そして、このファイルは AI だけでなく、人間の開発者にとっても重要な情報源になり得ます。
しかし、通常の書き方では AI には理解できても、人間にとっては使いづらいドキュメントになりがちです。
この記事では、シンプルにな工夫で両方にとって読みやすい CLAUDE.md を書くためのテクニックを紹介します。
CLAUDE.md の基本的な役割
CLAUDE.md は Claude Code のメモリ管理に使われます。
詳細は公式ドキュメントを参照してください。
今回着目するのは @path/to/import 構文による追加ファイルのインポートです。 CLAUDE.md の中に @path/to/import の構文でファイルを指定すると、Claude Code の起動時にそのファイルも読み込まれます。説明の都合上、@path/to/import と書いていますが、実際にCLAUDE.mdに書くときには、以下のように、 ` で囲まずに書きます。
# 正しい書き方
@path/to/import
# 間違った書き方
`@path/to/import`
これは、公式ドキュメントにも記載されているように、` (コードスパン) と ``` (コードブロック) 内では @path/to/import は無視されるためです。
潜在的な衝突を避けるため、インポートはmarkdownコードスパンとコードブロック内では評価されません。
https://docs.anthropic.com/ja/docs/claude-code/memory
人間にとって読みやすくする工夫
CLAUDE.md はClaude Code だけでなく、人間のオンボーディングドキュメントとしても有用です。しかし、人間が読む場合、@path/to/import 構文によるファイルのインポートはできません。
そこで、@path/to/import 構文の仕様と、CLAUDE.md はMarkdown ファイルであることを利用して、人間が読むときにも @path/to/import 構文でインポートしたファイルを読みやすくします。
ポイントは以下の2つの仕様をうまく活用することです。
-
@path/to/import構文はコードスパンとコードブロック内 では 無視される - Markdown ファイルでは、
CLAUDE .md を人間にも優しくするテクニック(link)でリンクを表現できる
つまり、以下のように書いても、CLAUDE.md としても、Markdown ファイルとしても有効な表現ができます。
[@path/to/import](path/to/import)
このように書くと、Claude Code の @path/to/import 構文としても機能しつつ、CursorやGitHubのMarkdownのプレビューではリンクとして表示され、クリックすればそのファイルが表示されます。
実際の使用例
例えば、Railsプロジェクトでこのテクニックを使うと、以下のように書くことができます。
- Rubyのバージョンは[@.ruby-version](.ruby-version)です。
- データベースのスキーマは[@db/schema.rb](db/schema.rb)です。
使用上の注意
- ファイルパスは
CLAUDE.mdからの相対パスで指定してください - 正しくインポートされているか、Claude Code の
/memoryコマンドで確認してください - Markdownプレビューでリンクが正しく機能することを確認してください
まとめ
[@path/to/import](path/to/import) という記法を使うことで、CLAUDE.mdを人間にとっても読みやすくできます。このシンプルなテクニックにより、AIのための設定ファイルが、同時に優れたプロジェクトドキュメントとしても機能します。
Xでは、このようなClaude Codeについての情報やAIについてのポストをしているので、興味のある方はぜひフォローしてください。
Views: 0
