agents-md-manager

AGENTS.md マネージャー

あらゆるプロジェクト向けに AGENTS.md ファイルと Codex CLI の設定を作成・管理します。

基本的なワークフロー

モードを判定します。

モード	条件	スクリプト
作成	新規プロジェクトで AGENTS.md が必要な場合	scripts/analyze_project.py を実行してから作成
更新	既存の AGENTS.md を監査する場合	scripts/validate_agents_md.py
変換	CLAUDE.md から移行する場合	scripts/convert_claude_to_agents.py
設定	config.toml を生成する場合	scripts/generate_config_toml.py
ルール	.rules ファイルを作成する場合	references/starlark-rules-spec.md を参照
スキル	.agents/skills/ のひな形を作成する場合	scripts/scaffold_codex_skill.py

1. プロジェクト分析

スタック、既存の設定、不足している項目を検出するために分析を実行します。

python3 ~/.claude/skills/agents-md-manager/scripts/analyze_project.py [project_path]

出力：技術スタック、コマンド、ディレクトリ構成、Codex 成果物の一覧（AGENTS.md、config.toml、.rules、.agents/skills/、CLAUDE.md からの変換候補）を含む JSON レポート。

2. AGENTS.md の生成

WHAT/WHY/HOW フレームワークを適用し、プレーンな Markdown のみを使用します。@import 構文や YAML フロントマターは使用しません。

推奨セクション

# Project Name

Brief description.

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Structure
- `/src` — Application source
- `/tests` — Test suites

## Conventions
- [Critical convention 1]
- [Critical convention 2]

## Boundaries
- Always: Run tests before committing
- Ask: Before adding production dependencies
- Never: Modify migration files directly

## Troubleshooting
- [Common issue and fix]

制約

• ファイルは 200 行未満、ネストされたサブディレクトリのファイルは 100 行未満を目標にします
• 32 KiB の上限（project_doc_max_bytes）を守ります
• プレーンな Markdown のみを使用します。@import と YAML フロントマターは使用しません
• エージェントのガードレールとして「境界」セクション（常に／確認／禁止）を含めます
• プロジェクトの種類に応じたテンプレートは references/templates.md を参照してください
• 検出と連結のルールは references/agents-md-spec.md を参照してください

3. CLAUDE.md の変換

既存の CLAUDE.md を AGENTS.md 形式に変換します。

python3 ~/.claude/skills/agents-md-manager/scripts/convert_claude_to_agents.py <claude_md_path> [output_path]

AGENTS.md と、変換内容および手動レビュー項目を記載した conversion_report.json を出力します。

主な変換：@import はインライン化またはネスト化されます。フックは .rules の提案に変換されます。スキルの呼び出しは文章に変換されます。Claude 固有のコマンドは削除されます。

フィールドごとの完全なマッピングについては、references/conversion-mapping.md を参照してください。

4. 設定の生成

~/.codex/config.toml（グローバル）または .codex/config.toml（プロジェクトスコープ）を生成します。

python3 ~/.claude/skills/agents-md-manager/scripts/generate_config_toml.py [--global | --project <path>] [--model MODEL] [--sandbox MODE]

対象：モデル、推論の強さ、パーソナリティ、サンドボックスモード、MCP サーバー、プロファイル、信頼済みプロジェクト、書き込み可能なルート。

フィールドの完全なリファレンスについては、references/config-toml-reference.md を参照してください。

5. Rules ファイル

コマンドの承認に使う Starlark の .rules ファイルを作成します。配置先は ~/.codex/rules/（グローバル）または .codex/rules/（プロジェクト）です。この形式には生成スクリプトがないため、Rules ファイルは手動で作成します。ディレクトリ内のすべての .rules ファイルが読み込まれ、統合されます。

よく使われるパターン：

• パッケージマネージャーのコマンド（npm、pip、cargo）を許可する
• 破壊的な操作（rm -rf、git push --force）をブロックする
• 機密性の高いコマンド（git commit、gh pr create）はレビューを求める

構文と例については、references/starlark-rules-spec.md を参照してください。

6. Codex スキル

Codex 形式で .agents/skills/<name>/ のひな形を作成します（Claude の .claude/skills/ とは形式が異なります）。

python3 ~/.claude/skills/agents-md-manager/scripts/scaffold_codex_skill.py <name> [--path <dir>]

name と description のフロントマター（Codex ではどちらも必須）を含む SKILL.md と、UI メタデータ用の agents/openai.yaml を作成します。

Claude スキルとの形式の違いについては、references/codex-skills-format.md を参照してください。

7. 監査チェックリスト

既存の AGENTS.md を更新する際は、以下を検証します。

• 32 KiB 未満ですか？（project_doc_max_bytes の上限）
• @import 構文はありませんか？（AGENTS.md ではサポートされていません）
• YAML フロントマターはありませんか？（AGENTS.md では使用しません）
• 記載されたすべてのコマンドをプロジェクト設定と照合して確認しましたか？
• ディレクトリの参照は実際の構成と一致していますか？
• 秘密情報や認証情報は含まれていませんか？
• ネストされた階層はルートと整合していますか？
• AGENTS.override.md との競合はありませんか？
• 200 行未満ですか？（200 行超は警告、400 行超はエラー）

自動監査を実行します。

python3 ~/.claude/skills/agents-md-manager/scripts/validate_agents_md.py [project_path]

8. ネストされた AGENTS.md（モノレポ）

モノレポでは、複数の階層に AGENTS.md を配置します。

/AGENTS.md              # Repo-wide conventions
/services/
  payments/
    AGENTS.override.md  # Payments-specific overrides
  search/
    AGENTS.md           # Search service conventions

• ディレクトリごとにファイルは最大 1 つです
• Codex はルートから CWD までを連結します（CWD に近いものほど後に現れ、先にあるものを上書きします）
• 同じディレクトリでは、AGENTS.override.md が AGENTS.md より優先されます
• ネストされた各ファイルの内容を絞り、100 行未満にします

統合に関する注意事項

• codex-orchestrator：このスキルは設定ファイルを作成し、codex-orchestrator はそれらを使ってサブエージェントを実行します
• claude-md-manager：Claude Code の CLAUDE.md 用の姉妹スキルです。変換モードを使って橋渡しします
• サブエージェントのプロファイル管理には、codex-orchestrator を使います

参考ドキュメント

ファイル	内容
references/agents-md-spec.md	AGENTS.md の検出、連結、上書き、サイズ制限、エージェント間の互換性
references/config-toml-reference.md	config.toml の全フィールドリファレンス
references/starlark-rules-spec.md	.rules ファイルの構文、prefix_rule()、判定タイプ
references/codex-skills-format.md	.agents/skills/ の形式、openai.yaml、Claude スキルとの違い
references/conversion-mapping.md	CLAUDE.md から AGENTS.md へのフィールドごとの対応
references/templates.md	プロジェクトタイプ別の AGENTS.md テンプレート