ccg-workflow 团队研究阶段实战：/ccg:team-research 如何并行探索代码库并产出可验证的约束集

• 人工智能
• AI 应用
• 开发工具
• CLI
• AI Agent
• dsh-plugin
• DeepSeek

本文聚焦 ccg-workflow 多模型协作开发系统中的Agent Teams 需求研究命令/ccg:team-research，完整剖析其"并行探索代码库 → 聚合约束集 → 消解歧义 → 落地研究文件"的执行流程，并结合仓库源码讲解底层codeagent-wrapper的参数机制。读完本文，你将掌握研究阶段（Research）在 8 阶段团队流水线中的定位、约束集驱动后续"零决策规划"的设计哲学，以及如何在 Claude 中手工复现这条双模型并行探索链路。

命令定位：研究是 8 阶段流水线的第二环

在 ccg-workflow 的 Agent Teams 统一工作流中（见 templates/commands-legacy/team.md），完整流水线被划分为 8 个阶段：

Phase 0: PRE-FLIGHT → 环境检测 Phase 1: REQUIREMENT → Lead 需求增强 → mini-PRD Phase 2: ARCHITECTURE → 后端模型∥前端模型 分析 + Architect teammate 出蓝图 Phase 3: PLANNING → Lead 拆任务 → 零决策并行计划 Phase 4: DEVELOPMENT → Dev×N teammates 并行编码 Phase 5: TESTING → QA teammate 写测试+跑测试 Phase 6: REVIEW → 后端模型∥前端模型 审查 + Reviewer teammate 综合判决 Phase 7: FIX → Dev teammate(s) 修复 Critical（最多 2 轮） Phase 8: INTEGRATION → Lead 全量验证 + 报告 + 清理

/ccg:team-research是这一体系中的研究（Research）阶段专用命令，位于需求增强之后、架构与规划之前。它的上游产物是增强后的结构化需求，下游产物是写入.claude/team-plan/<任务名>-research.md的约束集与成功判据，供/ccg:team-plan（templates/commands-legacy/team-plan.md）直接消费。

核心哲学：研究产出的是约束集，不是信息堆砌

team-research.md开篇即点明该命令的设计出发点，这是理解整条工作流的关键：

• 研究产出的是"约束集"（constraint sets），不是信息堆砌。每一条约束都在缩小解决方案空间（narrow the solution space）。
• 约束告诉后续阶段"不要考虑这个方向"，使 plan 阶段能产出零决策计划（zero-decision plan）——Builder teammates 拿到计划后只需机械执行，无需再做技术判断。
• 输出物：约束集合 + 可验证的成功判据，写入.claude/team-plan/<任务名>-research.md。

这一理念与仓库中 templates/engine/strategies/deep-research.md 的"深度研究"策略一脉相承：研究阶段绝不修改代码，只做探索与综合分析，最终给出结构化输出而非自由聊天式结论。

Guardrails：研究阶段的四条红线

命令在执行任何动作前必须遵守以下防护栏：

1. STOP! BEFORE ANY OTHER ACTION：必须先做 Prompt 增强（Step 0），这是强制且不可跳过的。
2. 按上下文边界划分探索范围，不按角色划分——严禁出现"架构师 agent""安全专家 agent"这类按职能拆分的子任务。
3. 多模型协作是强制的（mandatory）：必须同时调用{{BACKEND_PRIMARY}}（后端边界）与{{FRONTEND_PRIMARY}}（前端边界）两个外部模型。
4. 不做架构决策——只发现约束：架构选择留给后续 Architect/Plan 阶段。
5. 使用AskUserQuestion解决任何歧义，绝不假设。

其中"按上下文边界而非角色划分"是这套工作流最具辨识度的设计：每个探索边界自包含、无需跨边界通信，从而保证两个外部模型可以真正并行、互不干扰。

Step 0：MANDATORY Prompt 增强

研究阶段的第一步不是扫描代码，而是先增强需求：

• 分析$ARGUMENTS的意图、缺失信息、隐含假设；
• 补全为结构化需求：明确目标、技术约束、范围边界、验收标准；
• 后续所有步骤都使用增强后的需求，而不是原始输入。

这保证了两个外部模型拿到的是同一份完整、无歧义的任务描述，避免因原始需求过于口语化而导致探索方向漂移。仓库中 templates/commands/spec-research.md（新世代 spec 版本）同样把 Prompt 增强列为NON-NEGOTIABLE的第一步，可见这是贯穿整个 ccg-workflow 的通用铁律。

Step 1–2：代码库评估与探索边界定义

Step 1 代码库评估：用 Glob/Grep/Read 扫描项目结构，判断项目规模（单目录 vs 多目录），识别技术栈、框架与现有模式。

Step 2 定义探索边界（按上下文划分）：识别自然的上下文边界（不是功能角色），原文档给出三个典型示例：

• 边界 1：用户域代码（models, services, UI）
• 边界 2：认证与授权（middleware, session, tokens）
• 边界 3：基础设施（configs, builds, deployments）

每个边界应自包含，无需跨边界通信。在实际执行时，{{BACKEND_PRIMARY}}负责后端相关边界，{{FRONTEND_PRIMARY}}负责前端相关边界，形成两条互不重叠的探索线索。

Step 3：多模型并行探索——命令逐参数拆解

这是整个研究阶段的核心动作。CRITICAL 规则：必须在同一条消息中同时发起两个 Bash 调用（run_in_background: true），不能先调一个等结果再调另一个。

工作目录获取铁律

{{WORKDIR}}必须通过 Bash 执行pwd（Unix）或cd（Windows CMD）获取当前工作目录的绝对路径，禁止从$HOME或环境变量推断。这是为了防止环境变量与实际终端工作目录不一致导致外部模型探索了错误的目录。

第一条 Bash 调用（{{BACKEND_PRIMARY}} 后端探索）

Bash({ command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nROLE_FILE: ~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md\n<TASK>\n需求：<增强后的需求>\n探索范围：后端相关上下文边界\n</TASK>\nOUTPUT (JSON):\n{\n \"module_name\": \"探索的上下文边界\",\n \"existing_structures\": [\"发现的关键模式\"],\n \"existing_conventions\": [\"使用中的规范\"],\n \"constraints_discovered\": [\"限制解决方案空间的硬约束\"],\n \"open_questions\": [\"需要用户确认的歧义\"],\n \"dependencies\": [\"跨模块依赖\"],\n \"risks\": [\"潜在阻碍\"],\n \"success_criteria_hints\": [\"可观测的成功行为\"]\n}\nEOF", run_in_background: true, timeout: 3600000, description: "{{BACKEND_PRIMARY}} 后端探索" })

第二条 Bash 调用（{{FRONTEND_PRIMARY}} 前端探索，同一条消息）

Bash({ command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nROLE_FILE: ~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md\n<TASK>\n需求：<增强后的需求>\n探索范围：前端相关上下文边界\n</TASK>\nOUTPUT (JSON):\n{\n \"module_name\": \"探索的上下文边界\",\n \"existing_structures\": [\"发现的关键模式\"],\n \"existing_conventions\": [\"使用中的规范\"],\n \"constraints_discovered\": [\"限制解决方案空间的硬约束\"],\n \"open_questions\": [\"需要用户确认的歧义\"],\n \"dependencies\": [\"跨模块依赖\"],\n \"risks\": [\"潜在阻碍\"],\n \"success_criteria_hints\": [\"可观测的成功行为\"]\n}\nEOF", run_in_background: true, timeout: 3600000, description: "{{FRONTEND_PRIMARY}} 前端探索" })

等待结果

TaskOutput({ task_id: "<codex_task_id>", block: true, timeout: 600000 }) TaskOutput({ task_id: "<gemini_task_id>", block: true, timeout: 600000 })

失败处理与等待纪律

原文档对两条探索链路给出了截然不同的容错策略：

• ⛔前端模型失败必须重试：若前端模型调用失败，最多重试 2 次（间隔 5 秒）；3 次全败才允许跳过。
• ⛔后端模型结果必须等待：后端模型执行 5-15 分钟属正常现象，TaskOutput超时后必须继续轮询，禁止跳过。

这一不对称设计反映了两条探索链路的角色差异：后端模型是权威分析来源，其结论是约束集的主体；前端模型是补充视角，可以在极端情况下降级。

命令中的占位符与真实参数映射

上述命令中的{{LITE_MODE_FLAG}}、{{GEMINI_MODEL_FLAG}}等占位符在安装时由安装器替换为真实参数。从仓库源码 codeagent-wrapper/config.go 的参数解析逻辑看，codeagent-wrapper实际支持的 CLI 参数包括：

占位符展开后的命令形态例如：

~/.claude/bin/codeagent-wrapper --progress --backend codex --gemini-model gemini-2.5-pro - "/path/to/workdir"

后端注册表：BACKEND_PRIMARY 能取哪些值

从源码 codeagent-wrapper/config.go 的backendRegistry可以确认，当前 wrapper 支持的后端有 8 个：

var backendRegistry = map[string]Backend{ "codex": CodexBackend{}, "claude": ClaudeBackend{}, "gemini": GeminiBackend{}, "antigravity": AntigravityBackend{}, "agy": AntigravityBackend{}, "grok": GrokBackend{}, "kimi": KimiBackend{}, "opencode": OpencodeBackend{}, }

未指定--backend时默认使用codex（见 codeagent-wrapper/main.go 的defaultBackendName）。因此{{BACKEND_PRIMARY}}通常展开为codex，{{FRONTEND_PRIMARY}}通常展开为gemini，与项目"Claude 编排 + Codex 后端 + Gemini 前端"的定位一致；{{LITE_MODE_FLAG}}在轻量模式下展开为--lite。

ROLE_FILE：外部模型扮演的 analyzer 角色

命令中的ROLE_FILE: ~/.claude/.ccg/prompts/<backend>/analyzer.md指向安装后写入用户主目录的角色提示词。其仓库源文件对应 templates/prompts/codex/analyzer.md 与 templates/prompts/gemini/analyzer.md：

• Codex（后端视角）扮演 Technical Analyst：擅长架构评估、技术债分析、可扩展性、安全漏洞识别、技术栈评估与权衡分析；
• Gemini（前端视角）扮演 Design Analyst：擅长用户体验评估、设计系统分析、组件架构、可访问性合规与响应式设计。

两者都是ZERO file system write permission（只读沙箱），只输出结构化分析报告，不做任何代码修改——这从机制上保证了研究阶段"只发现约束、不产生变更"。

Step 4：聚合与综合——四类约束的统一

两个模型返回后，Lead 将探索输出合并为统一约束集，原文档定义了四个分类维度：

• 硬约束（Hard constraints）：技术限制、不可违反的模式；
• 软约束（Soft constraints）：惯例、偏好、风格指南；
• 依赖（Dependencies）：影响实施顺序的跨模块关系；
• 风险（Risks）：需要缓解的阻碍。

聚合时两个模型各自返回的 JSON 中的constraints_discovered、dependencies、risks字段正是这四个维度的直接输入。值得注意的是，输出模板中还有success_criteria_hints（可观测的成功行为）字段，它会在 Step 6 转化为可验证的成功判据。

Step 5：歧义消解——用 AskUserQuestion 系统性收敛

研究阶段不允许"猜"：

1. 编译优先级排序的开放问题列表（来自两个模型 JSON 中的open_questions字段）；
2. 用AskUserQuestion系统性呈现：分组相关问题、为每个问题提供上下文、在适用时建议默认值；
3. 将用户回答转化为额外约束，追加进约束集。

这一步骤保证了研究文件的"零开放问题残留"退出条件（Exit Criteria 之一）是可以达成的。

Step 6：写入研究文件——标准格式模板

聚合与消解完成后，将结果写入.claude/team-plan/<任务名>-research.md，原文档给出了完整格式：

# Team Research: <任务名> ## 增强后的需求 <结构化需求描述> ## 约束集 ### 硬约束 - [HC-1] <约束描述> — 来源：<后端/前端模型/用户> - [HC-2] ... ### 软约束 - [SC-1] <约束描述> — 来源：<后端/前端模型/用户> - [SC-2] ... ### 依赖关系 - [DEP-1] <模块A> → <模块B>：<原因> ### 风险 - [RISK-1] <风险描述> — 缓解：<策略> ## 成功判据 - [OK-1] <可验证的成功行为> - [OK-2] ... ## 开放问题（已解决） - Q1: <问题> → A: <用户回答> → 约束：[HC/SC-N]

每个约束都带来源标注（后端模型/前端模型/用户），使后续阶段能追溯每条约束的可信度与出处；成功判据采用[OK-N]编号，成为 team-plan 阶段拆分任务验收标准的直接依据。

Step 7：上下文检查点与阶段边界

• 报告当前上下文使用量；
• 提示用户：研究完成，运行 /clear 后执行 /ccg:team-plan <任务名> 开始规划。

这一提示明确了研究阶段与规划阶段的交接方式：研究文件落地后，研究阶段即告完成，不得越界进入规划或实现。同源的 spec 版本 templates/commands/spec-research.md 也强调"此阶段只产出提案 artifact，不修改任何源代码，生成后 STOP 并提示用户运行/ccg:spec-plan继续"。

Exit Criteria：研究完成的验收清单

- [ ] {{BACKEND_PRIMARY}} + {{FRONTEND_PRIMARY}} 探索完成 - [ ] 所有歧义已通过用户确认解决 - [ ] 约束集 + 成功判据已写入研究文件 - [ ] 零开放问题残留

四条退出条件与 Step 4–6 一一对应：两条探索链路都拿到结果、歧义全部收敛、产物落盘、开放问题清零。只有全部勾选，研究阶段才算正式完成。

源码级支撑：wrapper 的超时与并行机制

研究阶段两个 Bash 调用均设置timeout: 3600000（1 小时），而TaskOutput等待超时为600000（10 分钟）。wrapper 侧 codeagent-wrapper/main.go 定义的defaultTimeout = 7200（2 小时）为命令级兜底。两个超时层级的关系是：

• wrapper 进程本身最长运行 2 小时；
• 每次TaskOutput阻塞等待 10 分钟，超时后继续轮询（而非放弃），配合"后端模型 5-15 分钟属正常"的预期，确保长任务不被误杀。

此外，wrapper 支持resume <session_id> <task>恢复模式（见 config.go），若研究过程中断，可用会话 ID 无缝续跑，不必重新发起完整的双模型探索。

与 team-plan、team-exec 的流水线衔接

研究文件不是终点，而是规划阶段的"输入契约"：

1. /ccg:team-research（本文）：产出.claude/team-plan/<任务名>-research.md（约束集 + 成功判据）；
2. /ccg:team-plan：基于约束集做架构方案与任务拆分，产出.claude/team-plan/<任务名>.md，其TaskUpdate等待逻辑同样要求timeout: 600000，且"绝对不要 Kill 进程"（team-plan.md）；
3. /ccg:team-exec：读取计划文件，通过TeamCreate+Agent(team_name=...)spawn Builder teammates 并行实施（team-exec.md）。

正是因为研究阶段已经把"方向性决策"全部压缩成约束，team-plan 才能产出"零决策并行实施计划"，team-exec 的 Builder 才能"纯机械执行"。整条链路体现了 ccg-workflow 的核心设计思想：把判断力前置到研究阶段，把执行力留给并行阶段。

从 legacy 到 spec：研究范式的演进

值得注意的是，本命令（templates/commands-legacy/team-research.md）属于commands-legacy目录，仓库同时提供新世代的 templates/commands/spec-research.md。两者共享同一套研究哲学（约束集、上下文边界划分、双模型并行、AskUserQuestion 消歧），区别在于产物形态：

• legacy 版本：直接写入.claude/team-plan/<任务名>-research.md；
• spec 版本：通过openspec new change脚手架生成openspec/changes/<name>/proposal.md，并强调遵循 OPSX 规范、使用{{MCP_SEARCH_TOOL}}减少 grep/find 操作。

如果你在使用新版命令体系，/ccg:spec-research是本文所讲流程的规范化升级版；阅读本文的并行探索与约束聚合方法论，对两个版本都完全适用。

实战要点小结

• 研究阶段绝不写代码：外部模型处于只读沙箱（analyzer.md 明确 ZERO write permission），Lead 也只做聚合与消歧；
• 两个 Bash 调用必须同消息发起：这是实现"真正并行"的前提，串行调用会成倍拉长研究时长；
• 后端结果必须等到，前端失败可降级：两条链路的容错策略不同，不要混用；
• 每条约束都要带来源：[HC-1] ... — 来源：<后端/前端模型/用户>，保证可追溯；
• 成功判据必须可观测：[OK-N]描述的是"可验证的成功行为"，而非主观感受；
• 结束即交接：研究文件落盘后运行/clear并切换到/ccg:team-plan <任务名>，不越阶段。

• 人工智能
• AI 应用
• 开发工具
• CLI
• AI Agent
• dsh-plugin
• DeepSeek