agent-md-refactor

Agent MD Refactor

肥大化したエージェント指示ファイル（AGENTS.md、CLAUDE.md、COPILOT.md など）を、段階的開示（progressive disclosure）の原則に従ってリファクタリングします。必須事項はルートに残し、残りはリンクされたカテゴリ別ファイルに整理します。

---

トリガー

次の場合にこのスキルを使用します:

• 「AGENTS.md をリファクタリングして」/「CLAUDE.md をリファクタリングして」
• 「エージェント指示を分割して」
• 「CLAUDE.md ファイルを整理して」
• 「AGENTS.md が長すぎる」
• 「指示に段階的開示を適用して」
• 「エージェント設定をクリーンアップして」

---

クイックリファレンス

フェーズ	アクション	出力
1. 分析	矛盾を見つける	解決すべき競合の一覧
2. 抽出	必須事項を特定する	ルートファイル用のコア指示
3. 分類	残りの指示をグループ化する	論理的なカテゴリ
4. 構造化	ファイル階層を作成する	ルート + リンクされたファイル
5. 整理	削除対象をマークする	冗長・曖昧な指示

---

プロセス

フェーズ 1: 矛盾を見つける

互いに矛盾する指示を特定します。

確認すべき点:

• 相反するスタイルガイドライン（例: 「セミコロンを使う」対「セミコロンを使わない」）
• 競合するワークフロー指示
• 非互換なツールの設定
• 相互排他的なパターン

見つかった矛盾ごとに:

## Contradiction Found

**Instruction A:** [quote]
**Instruction B:** [quote]

**Question:** Which should take precedence, or should both be conditional?

先に進む前に、ユーザーに解決してもらいます。

---

フェーズ 2: 必須事項を特定する

ルートのエージェントファイルに入れるべきものだけを抽出します。ルートは最小限にすべきです。対象はすべてのタスクに当てはまる情報です。

必須の内容（ルートに残す）:

カテゴリ	例
プロジェクトの説明	1 文: 「分析用の React ダッシュボード」
パッケージマネージャー	npm 以外の場合のみ（例: 「pnpm を使用」）
標準外のコマンド	カスタムのビルド/テスト/型チェックコマンド
重要なオーバーライド	デフォルトを必ず上書きすべき事項
普遍的なルール	全タスクの 100% に適用されるもの

必須ではない（リンクされたファイルに移す）:

• 言語固有の規約
• テストに関するガイドライン
• コードスタイルの詳細
• フレームワークのパターン
• ドキュメント作成の標準
• Git ワークフローの詳細

---

フェーズ 3: 残りをグループ化する

残りの指示を論理的なカテゴリに整理します。

一般的なカテゴリ:

カテゴリ	内容
typescript.md	TS の規約、型パターン、strict モードのルール
testing.md	テストフレームワーク、カバレッジ、モックパターン
code-style.md	フォーマット、命名、コメント、構造
git-workflow.md	コミット、ブランチ、PR、レビュー
architecture.md	パターン、フォルダー構成、依存関係
api-design.md	REST/GraphQL の規約、エラー処理
security.md	認証パターン、入力検証、シークレット
performance.md	最適化ルール、キャッシュ、遅延読み込み

グループ化のルール:

1. 各ファイルは、そのトピックについて自己完結している必要があります
2. ファイル数は 3〜8 を目安にします（細かすぎず、粗すぎず）
3. ファイル名は明確に: {topic}.md
4. 実行可能な指示のみを含めます

---

フェーズ 4: ファイル構造を作成する

出力構造:

project-root/
├── CLAUDE.md (or AGENTS.md)     # Minimal root with links
└── .claude/                      # Or docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md

ルートファイルのテンプレート:

# Project Name

One-sentence description of the project.

## Quick Reference

- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`
- **Typecheck:** `pnpm typecheck`

## Detailed Instructions

For specific guidelines, see:
- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)
- [Git Workflow](.claude/git-workflow.md)
- [Architecture Patterns](.claude/architecture.md)

リンクされた各ファイルのテンプレート:

# {Topic} Guidelines

## Overview
Brief context for when these guidelines apply.

## Rules

### Rule Category 1
- Specific, actionable instruction
- Another specific instruction

### Rule Category 2
- Specific, actionable instruction

## Examples

### Good
\`\`\`typescript
// Example of correct pattern
\`\`\`

### Avoid
\`\`\`typescript
// Example of what not to do
\`\`\`

---

フェーズ 5: 削除対象をマークする

完全に削除すべき指示を特定します。

次の場合は削除:

基準	例	削除理由
冗長	「TypeScript を使う」（.ts プロジェクト内）	エージェントはすでに知っている
曖昧すぎる	「きれいなコードを書く」	実行可能ではない
明らかすぎる	「バグを埋め込まない」	コンテキストを無駄にする
デフォルトの動作	「わかりやすい変数名を使う」	標準的な慣行
古い	非推奨の API を参照している	もはや当てはまらない

出力形式:

## Flagged for Deletion

| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |
| "Don't commit secrets" | Agent already knows this |
| "Follow best practices" | Meaningless without specifics |

---

実行チェックリスト

[ ] Phase 1: All contradictions identified and resolved
[ ] Phase 2: Root file contains ONLY essentials
[ ] Phase 3: All remaining instructions categorized
[ ] Phase 4: File structure created with proper links
[ ] Phase 5: Redundant/vague instructions removed
[ ] Verify: Each linked file is self-contained
[ ] Verify: Root file is under 50 lines
[ ] Verify: All links work correctly

---

アンチパターン

避けるべきこと	理由	代わりに
すべてをルートに置く	肥大化し、保守が難しい	リンクされたファイルに分割する
カテゴリが多すぎる	断片化する	関連するトピックを統合する
曖昧な指示	トークンを浪費し、価値がない	具体的に書くか、削除する
デフォルトの重複記述	エージェントは既に知っている	必要な場合にのみ上書きする
深いネスト	移動しにくい	リンクを使ったフラットな構造にする

---

例

変更前（肥大化したルート）

# CLAUDE.md

This is a React project.

## Code Style
- Use 2 spaces
- Use semicolons
- Prefer const over let
- Use arrow functions
... (200 more lines)

## Testing
- Use Jest
- Coverage > 80%
... (100 more lines)

## TypeScript
- Enable strict mode
... (150 more lines)

変更後（段階的開示）

# CLAUDE.md

React dashboard for real-time analytics visualization.

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests with coverage
- `pnpm build` - Production build

## Guidelines
- [Code Style](.claude/code-style.md)
- [Testing](.claude/testing.md)
- [TypeScript](.claude/typescript.md)

---

検証

リファクタリング後は、次の点を確認してください。

1. ルートファイルが最小限である - 50行未満で、普遍的な情報のみを含む
2. リンクが機能する - 参照されているすべてのファイルが存在する
3. 矛盾がない - 指示が一貫している
4. 実行可能な内容である - すべての指示が具体的である
5. 網羅性が保たれている - 指示が失われていない（削除対象としてフラグが立てられたものを除く）
6. 各ファイルが自己完結している - リンクされた各ファイルが単独で理解できる

---