cc-codex-spec-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CC + Codex Spec Bootstrap Pipeline

CC + Codex 规范快速搭建管道

A multi-agent pipeline where Claude Code (CC) orchestrates and Codex executes in parallel. CC analyzes the repo with GitNexus + ABCoder, creates Trellis task PRDs, then Codex agents fill the coding specs — each with access to the same code intelligence MCP tools.

这是一个由Claude Code（CC）编排、Codex并行执行的多代理管道。CC通过GitNexus + ABCoder分析代码仓库，生成Trellis任务PRD，随后Codex代理填充编码规范——每个代理都可访问相同的代码智能MCP工具。

Why This Exists

设计初衷

AI coding agents produce better code when they have project-specific coding guidelines (not generic templates). But filling those guidelines manually is tedious. This skill automates the bootstrap:

You (Claude Code) analyze the repo architecture using GitNexus + ABCoder
You create Trellis tasks with rich PRDs containing architectural context + MCP tool instructions
Codex agents run those tasks in parallel, each filling one spec directory using the same MCP tools

The result: every spec file contains real code examples, actual patterns, and project-specific anti-patterns — not placeholder text.

当AI编码代理拥有项目专属的编码指南（而非通用模板）时，能生成更优质的代码。但手动填充这些指南十分繁琐。本技能可自动化完成搭建流程：

你（Claude Code）使用GitNexus + ABCoder分析仓库架构
你生成包含丰富架构上下文 + MCP工具指令的Trellis任务PRD
Codex代理并行执行这些任务，每个代理使用相同的MCP工具填充一个规范目录

最终结果：每个规范文件都包含真实代码示例、实际模式以及项目专属的反模式——而非占位文本。

Prerequisites

前提条件

Before running this skill, ensure these tools are set up. See references/mcp-setup.md for detailed installation instructions.

Tool	Purpose	Required
Trellis	Workflow framework with `.trellis/spec/` structure	Yes
GitNexus	Code → knowledge graph (Tree-sitter + KuzuDB)	Yes
ABCoder	Code → UniAST (ts-morph for TS, tree-sitter for others)	Yes
Codex CLI	Parallel task execution agent	Yes

Quick check:

bash

undefined

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

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

快速检查：

bash

undefined

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?

---

npx gitnexus status # GitNexus是否已索引？ abcoder list-repos # ABCoder是否已生成AST？ codex mcp list # Codex是否已配置MCP服务器？ python3 .trellis/scripts/get_context.py # Trellis是否已初始化？

---

Phase 1: Analyze the Repository

第一阶段：分析代码仓库

Step 1: Index with GitNexus

步骤1：使用GitNexus索引

bash

npx gitnexus analyze

This builds a knowledge graph: nodes (symbols), edges (dependencies), clusters (module groups), and execution flows. Takes ~5s for a typical monorepo.

After indexing, use GitNexus MCP tools to understand the architecture:

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

bash

npx gitnexus analyze

此命令会构建一个知识图谱：节点（符号）、边（依赖关系）、集群（模块组）和执行流。对于典型的单体仓库，耗时约5秒。

索引完成后，使用GitNexus MCP工具理解架构：

gitnexus_query({query: "plugin system"})        # 查找执行流
gitnexus_context({name: "SomeClass"})            # 360度符号视图
gitnexus_cypher({query: "MATCH (n:Class) RETURN n.name, n.file LIMIT 30"})  # 图谱查询

Step 2: Parse with ABCoder

步骤2：使用ABCoder解析

ABCoder provides precise AST analysis — function signatures, type definitions, cross-file dependency chains.

bash

undefined

ABCoder提供精准的AST分析——包括函数签名、类型定义、跨文件依赖链。

bash

undefined

Parse each package

解析每个包

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


Then use ABCoder MCP tools:

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"}]})

undefined

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


随后使用ABCoder MCP工具：

undefined

Step 3: Map the Architecture

步骤3：映射架构

Combine insights from both tools to understand:

Package boundaries — which packages exist, what each one does
Module clusters — GitNexus
```
clusters
```
resource shows functional groupings
Key patterns — Fetcher/Provider/Plugin/Adapter/Router patterns
Cross-package data flows — how data moves between packages
Error handling patterns — how errors propagate
State management — what's stateless vs stateful

Write down your findings — they go into the PRDs.

结合两个工具的分析结果，理解以下内容：

包边界——存在哪些包，每个包的功能是什么
模块集群——GitNexus的
```
clusters
```
资源展示了功能分组
核心模式——Fetcher/Provider/Plugin/Adapter/Router等模式
跨包数据流——数据如何在包之间流转
错误处理模式——错误如何传播
状态管理——无状态与有状态模块的区分

记录你的分析结果——这些内容将被写入PRD。

Phase 2: Create Trellis Tasks

第二阶段：创建Trellis任务

Task Decomposition Strategy

任务分解策略

Create one task per (package, layer) combination. Each task is independently executable by a Codex agent.

Typical decomposition for a monorepo:

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

Skip layers that don't apply (e.g., no frontend task for a pure CLI library).

为每个（包，层级）组合创建一个任务。每个任务可由Codex代理独立执行。

单体仓库的典型分解方式：

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

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

Create Task Directories

创建任务目录

bash

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

bash

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

Write PRDs

编写PRD

Each PRD must contain these sections. This is the critical part — the PRD is the entire context a Codex agent receives.

markdown

undefined

每个PRD必须包含以下部分。这是关键环节——PRD是Codex代理获取的全部上下文信息。

markdown

undefined

Fill <package> <layer> spec

填充<package> <layer>规范

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]

[使用下方的MCP工具模板]

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

删除不适用的模板文件
为模板未覆盖的模式创建新文件
若模板名称不符合需求，可重命名文件
更新index.md以反映最终的文件集合

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

仅修改分配给你的规范目录下的文件
不得修改源文件、其他规范目录或任务文件
不得执行git命令
可读取任何文件用于分析

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

包含来自实际代码库的真实代码示例（带文件路径）
已记录反模式
无剩余占位文本
index.md反映了实际的文件集合

Technical Notes

技术说明

Package path, language, framework, build tools, key deps.

undefined

包路径、语言、框架、构建工具、核心依赖。

undefined

MCP Tools Template for PRDs

PRD的MCP工具模板

Include this in every PRD so Codex knows how to call the tools:

markdown

undefined

在每个PRD中包含以下内容，以便Codex知晓如何调用工具：

markdown

undefined

Tools Available

可用工具

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

已配置两个MCP服务器——请结合使用以生成准确的规范：

GitNexus MCP (architecture-level: clusters, execution flows, impact)

GitNexus MCP（架构层面：集群、执行流、影响范围）

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 ..."})`

工具	用途	示例
`gitnexus_query`	按概念查找执行流	`gitnexus_query({query: "..."})`
`gitnexus_context`	360度符号视图	`gitnexus_context({name: "ClassName"})`
`gitnexus_impact`	影响范围分析	`gitnexus_impact({target: "X", direction: "upstream"})`
`gitnexus_cypher`	直接图谱查询	`gitnexus_cypher({query: "MATCH ..."})`

ABCoder MCP (symbol-level: AST nodes, signatures, cross-file deps)

ABCoder MCP（符号层面：AST节点、签名、跨文件依赖）

Tool Purpose Example

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: [...]})`

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: [...]})

工具用途示例

工具	用途	示例
`get_repo_structure`	完整文件列表	`get_repo_structure({repo_name: "pkg"})`
`get_file_structure`	文件中的所有节点	`get_file_structure({repo_name: "pkg", file_path: "src/..."})`
`get_ast_node`	代码 + 依赖 + 引用	`get_ast_node({repo_name: "pkg", node_ids: [...]})`

get_repo_structure

完整文件列表

get_repo_structure({repo_name: "pkg"})

get_file_structure

文件中的所有节点

get_file_structure({repo_name: "pkg", file_path: "src/..."})

get_ast_node

代码 + 依赖 + 引用

get_ast_node({repo_name: "pkg", node_ids: [...]})

Recommended Workflow

Phase 3: Launch Codex Agents

第三阶段：启动Codex代理

Run in Parallel

并行执行

Each task is independent — launch all agents simultaneously:

bash

undefined

每个任务相互独立——可同时启动所有代理：

bash

undefined

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."

undefined

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."

undefined

Monitor Progress

监控进度

Check which spec files have been filled:

bash

undefined

检查哪些规范文件已填充：

bash

undefined

Line counts — 0 or ~50 means still template

行数统计——0或约50行表示仍为模板

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

undefined

find .trellis/spec -name "*.md" -newer .trellis/tasks/ -exec ls -la {} ;

undefined

Review Results

审核结果

After all agents complete:

Check line counts — substantive files should be 80+ lines
Grep for leftover placeholders
Spot-check a few files for real code examples vs generic advice
Verify
```
index.md
```
in each directory reflects actual files

所有代理完成后：

检查行数——内容充实的文件应不少于80行
查找剩余的占位文本
抽查部分文件，确认包含真实代码示例而非通用建议
验证每个目录下的
```
index.md
```
是否反映了实际文件

Checklist

检查清单

GitNexus analyzed (
```
npx gitnexus analyze
```
)
ABCoder parsed all packages
GitNexus + ABCoder MCP configured for both Claude Code and Codex
Architecture mapped (packages, patterns, boundaries)
One task per (package, layer) created with
```
task.py create
```
Each PRD has: Context, MCP Tools, Files to Fill, Rules, Acceptance Criteria
Codex agents launched in parallel
Results reviewed — no placeholders, real code examples present

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

cc-codex-spec-bootstrap

Original

Translation

CC + Codex Spec Bootstrap Pipeline

CC + Codex 规范快速搭建管道

Why This Exists

设计初衷

Prerequisites

前提条件

Verify all tools

验证所有工具

Phase 1: Analyze the Repository

第一阶段：分析代码仓库

Step 1: Index with GitNexus

步骤1：使用GitNexus索引

Step 2: Parse with ABCoder

步骤2：使用ABCoder解析

Parse each package

解析每个包

Step 3: Map the Architecture

步骤3：映射架构

Phase 2: Create Trellis Tasks

第二阶段：创建Trellis任务

Task Decomposition Strategy

任务分解策略

Create Task Directories

创建任务目录

Write PRDs

编写PRD

Fill <package> <layer> spec

填充<package> <layer>规范

Goal

目标

Context

上下文

Tools Available

可用工具

Files to Fill

待填充文件

Important Rules

重要规则

Spec files are NOT fixed — adapt to reality

规范文件并非固定不变——需贴合实际

Parallel agents — stay in your lane

并行代理——各司其职

Acceptance Criteria

验收标准

Technical Notes

技术说明

MCP Tools Template for PRDs

PRD的MCP工具模板

Tools Available

可用工具

GitNexus MCP (architecture-level: clusters, execution flows, impact)

GitNexus MCP（架构层面：集群、执行流、影响范围）

ABCoder MCP (symbol-level: AST nodes, signatures, cross-file deps)

ABCoder MCP（符号层面：AST节点、签名、跨文件依赖）

Recommended Workflow

推荐工作流

Phase 3: Launch Codex Agents

第三阶段：启动Codex代理

Run in Parallel

并行执行

One terminal per task

每个任务使用一个终端

Monitor Progress

监控进度

Line counts — 0 or ~50 means still template

行数统计——0或约50行表示仍为模板

Check for remaining placeholders

检查剩余的占位文本

Newly created or modified files

新建或修改的文件

Review Results

审核结果

Checklist

检查清单