Spec 系统

Spec 系统让项目编码规范自动注入到所有子 Agent（外部模型调用和 Team Builder），无需人工在每次调用时手动粘贴规范。

目录结构

<project-root>/
└── .ccg/spec/
    ├── backend/
    │   └── index.md        # 后端编码规范
    ├── frontend/
    │   └── index.md        # 前端编码规范
    └── guides/
        └── index.md        # 跨模块通用指南

规范文件示例

backend/index.md:

# 后端编码规范

## API 设计
- RESTful 风格，路径用复数名词
- 统一响应格式：{ code, data, message }
- 错误码使用 HTTP 标准状态码

## 数据库
- 所有表必须有 created_at / updated_at
- 软删除使用 deleted_at 字段
- 索引命名：idx_表名_字段名

## 认证
- JWT Bearer Token 放在 Authorization header
- Token 过期时间 2h，Refresh Token 7d

自动注入机制

context.jsonl

每个任务目录下的 context.jsonl 文件定义了该任务需要注入的 spec 文件列表：

{"type": "spec", "path": ".ccg/spec/backend/index.md"}
{"type": "spec", "path": ".ccg/spec/guides/index.md"}
{"type": "plan", "path": ".ccg/tasks/add-jwt-auth/plan.md"}

注入时机

subagent-context.js Hook 在以下时机触发注入：

codeagent-wrapper 调用时 — 当 Claude 通过 wrapper 调用 Codex/Gemini 分析代码时，相关 spec 自动注入到 prompt
TeamCreate 时 — spawn Builder 队友时，该 Builder 负责模块对应的 spec 自动注入

注入流程

Claude 调用 codeagent-wrapper --backend codex
    ↓
subagent-context.js Hook 拦截 (PreToolUse)
    ↓
读取当前任务的 context.jsonl
    ↓
加载 .ccg/spec/backend/index.md 内容
    ↓
注入到 wrapper 的 prompt 前缀中
    ↓
Codex 执行时已经"知道"项目的后端规范

规范路由

引擎根据任务的领域分类自动选择注入哪些 spec 文件：

任务领域	注入的 spec
backend	`spec/backend/index.md` + `spec/guides/index.md`
frontend	`spec/frontend/index.md` + `spec/guides/index.md`
fullstack	全部 spec 文件

创建 Spec 文件

手动创建

在项目根目录创建 .ccg/spec/ 结构，按照上面的格式编写规范。

通过 /ccg:init 生成

/ccg:init 命令在初始化项目时会扫描代码库，自动生成初始 spec 骨架：

# 在项目根目录运行
/ccg:init

生成的骨架包含项目检测到的技术栈对应的常见规范模板。

与团队协作

推荐的 .gitignore 配置：

# CCG 任务状态（临时）
.ccg/tasks/

# CCG 规范（不要忽略，提交到 Git）
# .ccg/spec/  ← 不要加这行

规范的效果

有 spec 和没有 spec 的对比：

无 spec: Codex/Gemini 按自己的”习惯”写代码，可能用 snake_case 也可能用 camelCase，错误格式各异。

有 spec: 所有子 Agent 输出的代码都遵循统一的命名规范、API 格式、错误处理方式，与项目现有代码保持一致。