cc-codex-spec-bootstrap

CC + Codex 仕様ブートストラップパイプライン

Claude Code（CC）がオーケストレーションを行い、Codexが並行して実行するマルチエージェントパイプラインです。CC は GitNexus + ABCoder を使ってリポジトリを分析し、Trellis タスクの PRD を作成します。その後、Codex エージェントがコーディング仕様を埋めます。各エージェントは同じコードインテリジェンス MCP ツールを利用できます。

この仕組みがある理由

AI コーディングエージェントは、プロジェクト固有のコーディングガイドライン（一般的なテンプレートではなく）があると、より良いコードを生成できます。しかし、ガイドラインを手作業で埋めるのは面倒です。このスキルは、そのブートストラップを自動化します。

1. あなた（Claude Code）が GitNexus + ABCoder を使ってリポジトリのアーキテクチャを分析します
2. あなたが、アーキテクチャのコンテキストと MCP ツールの使い方を含む詳細な PRD を作成し、Trellis タスクを作成します
3. Codex エージェントが各タスクを並行して実行し、それぞれが同じ MCP ツールを使って 1 つの仕様ディレクトリを埋めます

その結果、すべての仕様ファイルに、プレースホルダーテキストではなく、実際のコード例、実際のパターン、プロジェクト固有のアンチパターンが含まれます。

---

前提条件

このスキルを実行する前に、以下のツールがセットアップされていることを確認してください。詳しいインストール手順については、references/mcp-setup.md を参照してください。

ツール	目的	必須
Trellis	.trellis/spec/ 構造を備えたワークフローフレームワーク	はい
GitNexus	コード → ナレッジグラフ（Tree-sitter + KuzuDB）	はい
ABCoder	コード → UniAST（TS には ts-morph、その他には tree-sitter）	はい
Codex CLI	並列タスク実行エージェント	はい

簡単な確認：

# Verify all tools
npx gitnexus status          # GitNexus indexed?
abcoder list-repos            # ABCoder has ASTs?
codex mcp list                # Codex has MCP servers?
python3 .trellis/scripts/get_context.py  # Trellis initialized?

---

フェーズ 1：リポジトリを分析する

ステップ 1：GitNexus でインデックスを作成する

npx gitnexus analyze

これにより、ノード（シンボル）、エッジ（依存関係）、クラスター（モジュールグループ）、実行フローからなるナレッジグラフが作成されます。一般的なモノレポなら約 5 秒かかります。

インデックスを作成したら、GitNexus MCP ツールを使ってアーキテクチャを把握します。

gitnexus_query({query: "plugin system"})        # Find execution flows
gitnexus_context({name: "SomeClass"})            # 360-degree symbol view
gitnexus_cypher({query: "MATCH (n:Class) RETURN n.name, n.file LIMIT 30"})  # Graph queries

ステップ 2：ABCoder で解析する

ABCoder は、関数シグネチャ、型定義、ファイル間の依存関係チェーンなど、正確な AST 分析を提供します。

# Parse each package
abcoder parse /path/to/package --lang typescript --name package-name --output ~/abcoder-asts

次に、ABCoder MCP ツールを使います。

get_repo_structure({repo_name: "package-name"})
get_file_structure({repo_name: "package-name", file_path: "src/core/types.ts"})
get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "ClassName"}]})

ステップ 3：アーキテクチャを整理する

両方のツールから得た情報を組み合わせて、以下を把握します。

• パッケージの境界 — どのパッケージがあり、それぞれが何をするか
• モジュールクラスター — GitNexus の clusters リソースに機能ごとのグループ分けが表示されます
• 主要なパターン — Fetcher／Provider／Plugin／Adapter／Router パターン
• パッケージ間のデータフロー — パッケージ間でデータがどのように移動するか
• エラー処理パターン — エラーがどのように伝播するか
• 状態管理 — ステートレスとステートフルの区別

調査結果を書き留めてください。PRD に記載します。

---

フェーズ 2：Trellis タスクを作成する

タスク分割の方針

（パッケージ、レイヤー）の組み合わせごとに 1 つのタスクを作成します。各タスクは Codex エージェントが個別に実行できます。

モノレポで一般的な分割例：

package-a/backend    → Task 1
package-a/frontend   → Task 2
package-b/backend    → Task 3
package-b/frontend   → Task 4
cross-layer-guide    → Task 5

該当しないレイヤーは省略してください（たとえば、純粋な CLI ライブラリにはフロントエンドのタスクは不要です）。

タスクディレクトリを作成する

python3 .trellis/scripts/task.py create "Fill <package> <layer> spec" --slug <package>-<layer>-spec

PRD を作成する

各 PRD には、以下のセクションを含める必要があります。ここが最も重要な部分です。PRD は Codex エージェントが受け取るすべてのコンテキストになります。

# Fill <package> <layer> spec

## Goal
One sentence: what to analyze, what files to fill.

## Context
Project-specific architectural knowledge you gathered in Phase 1.
Key concepts, patterns, abstractions — everything the agent needs
to understand the codebase without reading every file.

## Tools Available
[Use the MCP Tools Template below]

## Files to Fill
List each spec file with bullet points on what to document.
Include hints about which source files to analyze.

## Important Rules

### Spec files are NOT fixed — adapt to reality
- Delete template files that don't apply
- Create new files for patterns templates don't cover
- Rename files if template names don't fit
- Update index.md to reflect the final set

### Parallel agents — stay in your lane
- ONLY modify files under your assigned spec directory
- DO NOT modify source code, other spec directories, or task files
- DO NOT run git commands
- You may read any file for analysis

## Acceptance Criteria
- [ ] Real code examples from the actual codebase (with file paths)
- [ ] Anti-patterns documented
- [ ] No placeholder text remaining
- [ ] index.md reflects actual file set

## Technical Notes
Package path, language, framework, build tools, key deps.

PRD 用 MCP ツールテンプレート

Codex がツールの呼び出し方を把握できるよう、すべての PRD に以下を含めます。

## Tools Available

You have two MCP servers configured — use both for accurate specs:

### GitNexus MCP (architecture-level: clusters, execution flows, impact)
| Tool | Purpose | Example |
|------|---------|---------|
| `gitnexus_query` | Find execution flows by concept | `gitnexus_query({query: "..."})` |
| `gitnexus_context` | 360-degree symbol view | `gitnexus_context({name: "ClassName"})` |
| `gitnexus_impact` | Blast radius analysis | `gitnexus_impact({target: "X", direction: "upstream"})` |
| `gitnexus_cypher` | Direct graph queries | `gitnexus_cypher({query: "MATCH ..."})` |

### ABCoder MCP (symbol-level: AST nodes, signatures, cross-file deps)
| Tool | Purpose | Example |
|------|---------|---------|
| `get_repo_structure` | Full file listing | `get_repo_structure({repo_name: "pkg"})` |
| `get_file_structure` | All nodes in a file | `get_file_structure({repo_name: "pkg", file_path: "src/..."})` |
| `get_ast_node` | Code + deps + refs | `get_ast_node({repo_name: "pkg", node_ids: [...]})` |

### Recommended Workflow
1. GitNexus first — find relevant execution flows and clusters
2. ABCoder second — get exact code patterns and signatures
3. Read source files — for full context where needed
4. Write specs — with real code examples from steps 2-3

---

フェーズ 3：Codex エージェントを起動する

並行して実行する

各タスクは独立しているため、すべてのエージェントを同時に起動します。

# One terminal per task
codex -q "Read .trellis/tasks/<task-slug>/prd.md and execute the task. Use GitNexus and ABCoder MCP tools to analyze the codebase, then fill all spec files listed in the PRD."

進捗を確認する

どの仕様ファイルが埋められたかを確認します。

# Line counts — 0 or ~50 means still template
find .trellis/spec -name "*.md" -exec sh -c 'echo "$(wc -l < "$1") $1"' _ {} \; | sort -rn

# Check for remaining placeholders
grep -rl "To be filled" .trellis/spec/

# Newly created or modified files
find .trellis/spec -name "*.md" -newer .trellis/tasks/ -exec ls -la {} \;

結果を確認する

すべてのエージェントが完了したら：

1. 行数を確認します。内容の充実したファイルは 80 行以上あるはずです
2. プレースホルダーが残っていないか grep で検索します
3. いくつかのファイルを抜き打ちで確認し、一般的なアドバイスではなく実際のコード例が含まれているか確認します
4. 各ディレクトリの index.md に、実際のファイルが反映されていることを確認します

---

チェックリスト

• GitNexus の解析を実施（npx gitnexus analyze）
• ABCoder ですべてのパッケージを解析
• Claude Code と Codex の両方に GitNexus + ABCoder MCP を設定
• アーキテクチャをマッピング（パッケージ、パターン、境界）
• 各（パッケージ、レイヤー）につき 1 つのタスクを task.py create で作成
• 各 PRD に以下を記載：コンテキスト、MCP ツール、入力するファイル、ルール、受け入れ基準
• Codex エージェントを並列で起動
• 結果をレビュー — プレースホルダーがなく、実際のコード例が含まれている