Knowledge Reorg Command

AGENTS.md・Skills・docsを「AI Agent Knowledge Architecture Policy」に基づいて分析・整理する。

入力

$ARGUMENTS

ポリシー（AI Agent Knowledge Architecture）

知識を以下の3層に分離する。実際のパスはリポジトリやAIエージェントごとに異なる。

層	役割
エントリポイント	ナビゲーション + ポリシー（軽量、300行以下推奨）
ドキュメント	リポジトリ知識（アーキテクチャ、モジュール説明、依存関係）
スキル	実行可能なワークフロー（手順、コマンド、チェックリスト）

マルチエージェント対応戦略

推奨: AGENTS.mdを共通エントリポイントとし、各エージェント固有ファイルからインポートで参照する。

AGENTS.md                ← 共通エントリポイント（本体）
.claude/CLAUDE.md        ← @../AGENTS.md でインポート
.gemini/GEMINI.md        ← @../AGENTS.md でインポート
（Codex CLI）             ← AGENTS.md を直接読込（設定不要）
（Kiro CLI）              ← AGENTS.md を直接読込（設定不要）

エージェント固有ファイルの設定例

Claude Code (.claude/CLAUDE.md):

@../AGENTS.md

Gemini CLI (.gemini/GEMINI.md):

@../AGENTS.md

または.gemini/settings.jsonで:

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Codex CLI / Kiro CLI: AGENTS.mdをネイティブに読込。追加設定不要。

エージェント別ファイル配置リファレンス

エントリポイント

エージェント	固有ファイル	グローバル	AGENTS.md
Claude Code	`.claude/CLAUDE.md`	`~/.claude/CLAUDE.md`	`@../AGENTS.md`でインポート
Kiro CLI	`.kiro/steering/*.md`	`~/.kiro/steering/*.md`	直接読込
Codex CLI	なし（AGENTS.md標準）	`~/.codex/AGENTS.md`	直接読込
Gemini CLI	`.gemini/GEMINI.md`	`~/.gemini/GEMINI.md`	`@../AGENTS.md`でインポート or settings.json

補足:

Kiro CLIはsteering体系（product.md/tech.md/structure.md）で構造化指示を管理
Codex CLIはAGENTS.override.mdによる上書き機構あり
Gemini CLIは@構文でネストインポート対応（循環検出あり、最大深度5）

スキル配置

エージェント	プロジェクト	ユーザー
Claude Code	`.claude/skills/<name>/SKILL.md`	`~/.claude/skills/<name>/SKILL.md`
Kiro CLI	`.kiro/skills/<name>/SKILL.md`	なし（エージェント経由）
Codex CLI	`.agents/skills/<name>/SKILL.md`	`~/.agents/skills/<name>/SKILL.md`
Gemini CLI	`.agents/skills/<name>/SKILL.md` or `.gemini/skills/<name>/SKILL.md`	`~/.agents/skills/<name>/SKILL.md` or `~/.gemini/skills/<name>/SKILL.md`

共通: 全エージェントがSKILL.mdファイルを採用（Agent Skillsオープンスタンダードに収束傾向）。

ドキュメント

ドキュメントディレクトリはエージェント標準では規定されていない。docs/が一般的な慣例。

0) パス検出（実行時に最初に行う）

整理を始める前に、対象リポジトリで以下を検出する:

エントリポイント: 上表を参考に、存在するファイルを特定（複数エージェント対応の場合はすべて列挙）
ドキュメントディレクトリ: docs/が存在するか、なければ作成先を提案
スキルディレクトリ: 上表を参考に、存在するディレクトリを特定
対象エージェント: どのエージェント向けに整理するかを確認

検出結果をAskUserQuestionでユーザーに確認し、以降の作業で使用する。

エントリポイントに含めるべきもの

リポジトリ概要
ドキュメントへのナビゲーション
エージェント行動ルール
スキルへの参照

エントリポイントに含めてはいけないもの

詳細なアーキテクチャ説明
データベーススキーマ
長い説明文
運用手順（スキルへ）

ドキュメントに含めるべきもの

システムアーキテクチャ
リポジトリ構造の説明
モジュール説明
依存関係
インフラ概要
設計思想

スキルに含めるべきもの

ステップバイステップの手順
実行コマンド
バリデーションルール
チェックリスト

手順

1) 現状分析

まず「0) パス検出」でエントリポイント・ドキュメントディレクトリ・スキルディレクトリを特定した上で、以下を分析する:

エントリポイントの行数とトークン概算を計測
- 300行以上なら「肥大化」と判定
- 含まれている情報の種類を分類（ナビゲーション/知識/手順/ポリシー）
ドキュメントディレクトリの状態を確認
- 存在するか
- どの程度の知識が格納されているか
スキルディレクトリの状態を確認
- 各スキルの役割分類
- 知識がスキルに混入していないか
Serena memoryの状態を確認（--migrate-memory指定時）
- .serena/memories/の内容を一覧
- 各メモリーの分類（知識→ドキュメント / 手順→スキル / 一時的→削除候補）

2) 分析レポート作成

以下の形式でユーザーに報告する:

## 現状分析レポート

### エントリポイント（{検出したファイル名}）
- 行数: X行（目標: 300行以下）
- 状態: 適正 / 肥大化
- 含まれる情報の内訳:
  - ナビゲーション: X行
  - 知識（ドキュメント移動候補）: X行
  - 手順（スキル移動候補）: X行
  - ポリシー: X行

### ドキュメント（{検出したパス}）
- 状態: 未作成 / 不足 / 適正
- 不足している知識: [リスト]

### スキル（{検出したパス}）
- 状態: 適正 / 知識混入あり
- 問題のあるスキル: [リスト]

### Serena Memory（該当時）
- 移行対象: X件
  - ドキュメント移動: X件
  - スキル移動: X件
  - 削除候補: X件

3) 整理計画の提案

AskUserQuestionで以下を確認:

対象スコープ: AGENTS.md / skills / docs / all
実行モード: dry-run（レポートのみ） / 実行（実際に変更）
Serena memory移行: する / しない

4) 実行（dry-runでない場合）

エントリポイント整理

詳細な知識をドキュメントディレクトリに抽出
手順をスキルディレクトリに抽出
エントリポイントをナビゲーション+ポリシーのみに圧縮
ドキュメントへのリンクを追加

ドキュメント整理

必要なサブディレクトリを作成（architecture/, modules/など）
エントリポイントから抽出した知識を配置
Serena memoryから移行（該当時）

スキル整理

知識が混入しているスキルを特定
知識部分をドキュメントに抽出し、スキルからはリンク参照に変更

Serena memory移行（該当時）

以下のルールで再配置:

Memory種別	移行先
リポジトリ構造	ドキュメント
アーキテクチャ説明	ドキュメント
モジュール説明	ドキュメント
依存関係	ドキュメント
エージェント手順	スキル
一時的な調査結果	削除
タスク履歴	削除

5) 検証

整理後に以下を検証:

エントリポイントが300行以下か
3層構造（エントリポイント/ドキュメント/スキル）が守られているか
リンク切れがないか
マルチエージェント互換性（Claude Code, Codex CLI, Gemini CLI, Kiro）

6) 完了報告

## 整理完了レポート

### 変更サマリー
- エントリポイント: X行 → Y行（Z行削減）
- ドキュメント: X件のファイルを追加/更新
- スキル: X件のスキルを整理
- Serena memory: X件を移行、Y件を削除候補

### 作成/変更したファイル
- [ファイル一覧]

### 次のステップ
- [ ] 変更内容のレビュー
- [ ] 不要なSerena memoryの削除（手動確認推奨）
- [ ] コミット＆PR作成（`/ndf:pr`）

マルチエージェント互換性

整理時は以下を遵守:

ツール固有のフォーマットを避ける
Serena固有の知識ストレージに依存しない
プレーンMarkdownを使用（図はmermaidで記述）
安定したディレクトリ構造を維持

注意事項

--dry-run指定時はレポートのみ出力し、ファイルを変更しない
大規模な変更前は必ずユーザー確認を取る
既存のリンクやパス参照を壊さないよう注意する
AGENTS.md内のClaude Code固有設定（CLAUDE.md参照など）は保持する

knowledge-reorg