cc-codex-spec-bootstrap

CC + Codex 规范引导流程

一个多 Agent 流程：Claude Code（CC）负责协调，Codex 并行执行。CC 使用 GitNexus + ABCoder 分析代码库，创建 Trellis 任务 PRD，然后由 Codex Agent 填充编码规范——每个 Agent 都能访问相同的代码智能 MCP 工具。

为什么需要这个流程

AI 编码 Agent 在获得项目专属编码指南（而非通用模板）后，能写出更好的代码。但手动填写这些指南很繁琐。此技能可自动完成引导流程：

1. 你（Claude Code）使用 GitNexus + ABCoder 分析代码库架构
2. 你创建 Trellis 任务，其中包含丰富的 PRD，涵盖架构上下文和 MCP 工具说明
3. Codex Agent 并行运行这些任务，每个 Agent 使用相同的 MCP 工具填充一个规范目录

最终，每个规范文件都包含真实的代码示例、实际使用模式和项目专属反模式，而非占位文本。

---

前置条件

运行此技能前，请确保已设置以下工具。详细安装说明请参阅 references/mcp-setup.md。

工具	用途	必需
Trellis	采用 .trellis/spec/ 结构的工作流框架	是
GitNexus	代码 → 知识图谱（Tree-sitter + KuzuDB）	是
ABCoder	代码 → UniAST（TS 使用 ts-morph，其他语言使用 tree-sitter）	是
Codex CLI	并行任务执行 Agent	是

快速检查：

# 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 任务

任务分解策略

每个（包，层）组合创建一个任务。每个任务都可由 Codex Agent 独立执行。

单体代码库的典型分解方式：

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

跳过不适用的层（例如，纯命令行库无需前端任务）。

创建任务目录

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

编写 PRD

每份 PRD 都必须包含以下部分。这是关键所在——PRD 是 Codex Agent 接收的全部上下文。

# 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 工具模板

将以下内容添加到每份 PRD 中，以便 Codex 知道如何调用这些工具：

## 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 Agent

并行运行

每项任务彼此独立——同时启动所有 Agent：

# 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 {} \;

审查结果

所有 Agent 完成后：

1. 检查行数——内容充实的文件应至少有 80 行
2. 搜索残留的占位文本
3. 抽查几个文件，确认其中包含真实代码示例，而非通用建议
4. 验证每个目录中的 index.md 是否反映实际文件

---

检查清单

• 已完成 GitNexus 分析（npx gitnexus analyze）
• ABCoder 已解析所有包
• 已为 Claude Code 和 Codex 配置 GitNexus + ABCoder MCP
• 已绘制架构图（包、模式、边界）
• 已使用 task.py create 为每个（包、层）创建一个任务
• 每份 PRD 均包含：上下文、MCP 工具、待填写文件、规则、验收标准
• 已并行启动 Codex Agent
• 已审查结果 — 无占位符，且包含真实代码示例