claude-md-writer

CLAUDE.md Writer

Anthropic 公式のベストプラクティスに従って CLAUDE.md ファイルを作成、最適化するためのスキルです。

黄金律

一行ごとに、次のように問いかけます。「これを削除すると、Claude は間違いを犯すだろうか？」 そうでなければ、削除してください。肥大化した CLAUDE.md は、Claude に指示を無視させる原因になります。

「CLAUDE.md は、コードベースにある『明文化されていない知識』だと考えてください」

クイックツール

• /init - プロジェクトの構造に基づいて初期 CLAUDE.md を生成します
• # キー - セッション中に指示を動的に追加します

@import 構文

CLAUDE.md はほかのファイルをインポートできます。

See @README.md for overview and @package.json for commands.
Git workflow: @docs/git-instructions.md

参考ドキュメント

例と検証チェックリストについては、以下を参照してください。

• references/good-example.md - 適切に構成された CLAUDE.md の例
• references/bad-example.md - 避けるべき一般的なアンチパターン
• references/checklist.md - 品質検証チェックリスト
• references/dead-weight-audit.md - 無駄な記述の監査（指示を削減するための5つの基準）

含める内容と除外する内容

含める内容	除外する内容
Claude が推測できない Bash コマンド	コードを読めば Claude が把握できる内容
デフォルトと異なるコードスタイルのルール	標準的な言語の規約
テストの手順と推奨するテストランナー	詳細な API ドキュメント（代わりにリンクします）
リポジトリのエチケット（ブランチ名、PR）	頻繁に変更される情報
プロジェクト固有のアーキテクチャ上の決定事項	長い説明やチュートリアル
開発環境の特殊な点（環境変数）	ファイルごとの説明
よくある落とし穴や分かりにくい動作	自明なプラクティス

CLAUDE.md とスキルの違い

CLAUDE.md	スキル
常に適用される幅広いルール	必要な場合にのみ使うドメイン知識
コードスタイルとワークフロー	再利用可能な専門ワークフロー
リポジトリの規約	コンテキストによって変わる情報
各セッションで読み込まれる	必要に応じて読み込まれる

コンテンツの振り分け

CLAUDE.md に内容を追加する前に、次のように判断します。

内容が以下に該当する場合	その場合は...
すべてのタスクに適用されるルール	CLAUDE.md に追加します
特定のドメイン知識	スキルの作成を提案します
特定の状況でのみ適用されるワークフロー	スキルの作成を提案します
頻繁に変更される情報	追加せず、ドキュメントにリンクします

ユーザーが条件付きの情報（「X を扱うときは...」「Y の種類のタスクでは...」）を追加したい場合は、別のスキルを作成するよう提案してください。

使用方法

呼び出し	動作
/claude-md-writer	一連のプロセスを実行します。プロジェクトを分析し、CLAUDE.md を作成または改善します
/claude-md-writer actualiza con la sesion	現在のセッションから関連情報を抽出し、CLAUDE.md に追加します
/claude-md-writer agrega regla: [descripcion]	適切な形式で特定のルールを追加します
/claude-md-writer revisa y optimiza	既存の CLAUDE.md を監査し、重複を削除して強調を改善します
/claude-md-writer audita	無駄な記述を監査し、現在の設定に対して5つの基準を適用します（references/dead-weight-audit.md を参照）
/claude-md-writer convierte a skill	スキルにすべき内容を特定し、切り出します

プロセス

ステップ 1：プロジェクトを分析する

技術スタック、プロジェクト構造、既存のドキュメントを特定します。

ステップ 2：3つの観点を適用する

観点	答える質問
WHAT	このプロジェクトは何ですか？技術スタックは何ですか？構造はどうなっていますか？
WHY	なぜ存在するのですか？どのような問題を解決しますか？
HOW	どのように作業しますか？コマンドは何ですか？ワークフローはどうなっていますか？

ステップ 3：ベストプラクティスに従って記述する

長さ：200 行未満（理想は約 100 行）にします。

構成（順番どおり）：

1. リポジトリの概要（1 段落）
2. これが存在する理由（目的、対象ユーザー）
3. クイックスタートとコマンド（説明付きの bash）
4. アーキテクチャの概要（主要なパターン）
5. 重要な開発ルール（強調する）
6. 参考資料（詳細ドキュメントへのリンク）

重要なルールの強調：

- **CRITICAL**: [Never violate this]
- **IMPORTANT**: [Always do this]

段階的な情報開示：

• コードスニペットではなく、ファイルへの参照を使用します
• 詳細なトピックについては、外部ドキュメントにリンクします
• CLAUDE.md は普遍的な指示に絞ります

ステップ 4：チェックリストで確認する

仕上げる前に、references/checklist.md のチェックリストを確認します。

テンプレート

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Repository Overview

[One paragraph: what this project is, tech stack, main purpose]

## Why This Exists

[What problem it solves, who uses it, business context]

## Quick Start & Commands

\`\`\`bash
npm ci        # Install dependencies
npm start     # Start dev server
npm test      # Run tests
npm run build # Production build
\`\`\`

## Architecture Overview

[Key patterns, folder structure, main concepts - keep brief]

## Key Development Rules

- **CRITICAL**: [Most important rule that must never be violated]
- **IMPORTANT**: [Second most important rule]

## References

- `/docs/` - Detailed documentation
- `README.md` - Project readme

不要な記述の監査

ユーザーからセットアップの監査を依頼されたら、references/dead-weight-audit.md の 5 つの基準を各ルールに適用します。

1. デフォルト？ — Claude は指示されなくてもすでに実行します
2. 矛盾？ — セットアップ内の別のルールと矛盾しています
3. 重複？ — 別のルールまたはプロセスでカバーされています
4. 場当たり的な修正？ — 特定の悪い出力を修正するために追加されています
5. 曖昧？ — 解釈がその都度異なります

期待される出力：

• 削除する項目の一覧と、それぞれの理由（1 行）
• ファイル間で見つかった矛盾の一覧
• 不要な記述を除いた CLAUDE.md のクリーンなバージョン

**監査後のプロセス：**削除 → 典型的なタスクを 3 つ試す → 問題が起きたものだけを再度追加する。

避けるべきアンチパターン

アンチパターン	問題点	代わりに行うこと
コードスニペット	古くなり、トークンを無駄にします	file:line 形式の参照を使用します
スタイルルール	LLM が決定論的なタスクを行うと遅くなります	リンターを設定します
詰め込みすぎ	指示の効果が薄れます	200 行未満に保ちます
強調なし	重要なルールと軽微なルールが同じ重みになります	CRITICAL/IMPORTANT を使用します
自動生成	プロジェクト固有のニュアンスを見落とします	手作業で作成します
ドメイン知識	毎回のセッションでの負担が増えます	スキルに移します