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. ファイルが自己完結している - リンク先の各ファイルが単独で機能する

---

---

クレジットと帰属

このスキルは、 Softaworks による優れた成果を基にしています。

元のリポジトリ：https://github.com/softaworks/agent-toolkit

このスキルコレクションの形成に貢献した、寛大なオープンソースの提供に対し、Softaworks に特別な感謝を申し上げます。 このスキルコレクション向けに webconsulting.at が改変しました