cold-start

冷启动：Memory Bank + Agents 引导（绿地项目与棕地项目）

摘要

注意：cold-start 是用于一体化引导的包技能。 不要将它与生成项目中的命令 /cold-start 混淆：该命令是在目标仓库中创建骨架之后使用的轻量级路由器。 如需模块化使用，优先选择单独技能：mb-init（骨架）、mb-analysis（可选的创意探索）、mb-from-prd（绿地项目）、mb-map-codebase（棕地项目）、mb-review（审查）、mb-execute（实现）、mb-verify（UAT）、mb-red-verify（语义对抗式验证）。

• **功能：**创建 Memory Bank 骨架、编写 Agent 入口文件，并将仓库路由到合适的工作流。
• **适用场景：**你需要一个入口，既能用于有 PRD 的新项目，也能用于需要先进行代码映射的现有代码库。
• **输入：**仓库根目录，以及 prd.md／需求文本或现有代码库。
• 输出：.memory-bank/、.tasks/、.protocols/、Agent 入口文件，以及绿地项目或棕地项目的下一步操作。

支持的场景：

• 仅有创意：仓库有初步创意，但尚无稳定的 PRD；可选地通过 /analysis、/brainstorm 和 /brief 进行规划。
• 概念明确：仓库的方向足以编写产品简报；通常先运行 /brief，然后仅在项目原则尚未达到 ratified|partial 状态时运行 /constitution，再运行 /write-prd。
• 绿地项目：仓库有 prd.md 或需求文本，但尚无代码。
• 棕地项目：仓库已有代码，需要先编写现状文档，再规划变更。

---

不可妥协的原则

1) 编排者与工作者

• **你（主 Agent）是编排者。**你负责规划和协调。
• 工作者（子 Agent）负责执行繁重工作（扫描大量文件、生成长篇报告）。
• 最大深度 = 2：编排者 → 子 Agent。禁止使用子子 Agent。

2) .tasks/ 是运行时记忆（НЕ Memory Bank）

• 每个 Agent 进程都会获得唯一的任务文件夹：.tasks/TASK-XXX/。
• 子 Agent 在其中写入详细结果，并且只向编排者返回简短摘要。

3) 通过设计避免冲突

• 按照互不重叠的文件集拆分工作。
• 如果无法避免重叠，则为每个 Agent 使用 git 分支／工作树，之后再合并。

4) 并行限制

• 最多并行运行 5–7 个子 Agent。
• 如果运行时支持多工具调用：在单个编排者轮次中并行启动子 Agent。

5) 文档优先

完成任何有意义的工作单元后：

1. 趁上下文尚新时更新 Memory Bank。
2. 然后更改代码／提交。

---

必须创建／维护的输出

仓库根目录

• AGENTS.md（规范文件，简短，约 100 行）
• CLAUDE.md → 指向 AGENTS.md 的符号链接（或副本）
• （可选） GEMINI.md → 指向 AGENTS.md 的符号链接（或副本）

仓库文件夹

• .memory-bank/ — 持久知识库
• .tasks/ — 操作运行时记忆
• .protocols/ — 基于文件的协议（计划／决策日志／恢复）

步骤 0 — 检测环境（不要猜测）

1. 检查你有哪些工具：

   • 是否可用 Codex？（Codex CLI / MCP 工具）
   • 是否可用 Claude Code？（CLI claude、子 Agent）
   • 是否有浏览器工具？（Playwright / agent-browser / CDP MCP）

2. 决定主要引擎：

   • 如果在 Codex 中工作：使用 gpt-5.2-high 进行实现和审查（关键审查优先使用全新会话）。
   • 如果在 Claude Code 中工作：使用子 Agent 进行分析，并使用 Opus 进行综合；也可以通过 shell 调用 Codex，以获得第二意见或结构化审查。
   • 如果 Codex 和 Claude 都可用（双引擎）：使用 Claude 进行广泛上下文扫描和综合，使用 Codex 进行结构化审查和实现。通过在另一个引擎上运行审查步骤，对关键输出（MB 合规性、架构）进行交叉验证。混合工作流请参见步骤 4。

如果无法通过 UI 控制 Codex 模型选择，请创建项目 .codex/config.toml 配置文件组（参见步骤 1.5）。

---

步骤 1 — 搭建骨架

1.1 创建目录

创建以下目录（如果尚不存在）：

• .memory-bank/

  • mbb/
  • architecture/
  • guides/
  • adrs/
  • tech-specs/
  • domains/ (可选，但推荐)
  • contracts/ (可选，但推荐)
  • states/ (可选，但推荐)
  • runbooks/ (可选，但推荐)
  • workflows/ (可选；如果已在使用 wfs/，也可以保留)
  • quality/ (可选，但推荐)
  • testing/
  • skills/
  • epics/
  • features/
  • schemas/ (JSON 架构，包括任务记录)
  • tasks/ (空的 JSON 任务索引，之后用于 /prd-to-tasks、已编入索引的任务记录和计划)
  • commands/ (供人类/Agent 使用的斜杠命令规范)
  • agents/ (子 Agent 提示词库)
  • archive/
  • bugs/

• .tasks/

• .protocols/

1.2 创建核心文件（使用模板）

使用以下位置中的模板：

• ./references/shared-structure-template.md

至少必须创建：

• AGENTS.md
• CLAUDE.md 符号链接/副本
• .memory-bank/index.md
• .memory-bank/constitution.md
• .memory-bank/mbb/index.md
• .memory-bank/spec-index.md
• .memory-bank/glossary.md
• .memory-bank/invariants.md
• .memory-bank/product.md
• .memory-bank/requirements.md
• .memory-bank/schemas/task.schema.json
• .memory-bank/tasks/index.json
• .memory-bank/testing/index.md

还要在 .memory-bank/commands/ 下创建命令规范（使用 references/commands/*）。 如果软件包中包含可选的分析命令规范（analysis.md、brainstorm.md、brief.md），也要创建这些文件。 还要为 /constitution 命令创建 constitution.md，该命令用于创建或更新 .memory-bank/constitution.md。

1.2.1 创建原生技能（代理命令）

创建轻量级代理技能，使命令能在各运行环境中原生运行：

• .claude/skills/<name>/SKILL.md → Claude Code + OpenCode
• .agents/skills/<name>/SKILL.md → Codex CLI + OpenCode

每个代理只需写明：Read and follow the instructions in .memory-bank/commands/<name>.md。 这样，所有三种工具都能原生使用命令（/mb、/constitution、/prd、/execute 等）。

init-mb.js 脚本会自动创建这两组文件。

Agent 会在初始化早期读取 .memory-bank/constitution.md。它是用于指导项目决策的简明原则层，而不是 .memory-bank/invariants.md、.memory-bank/contracts/*、.memory-bank/spec-index.md 或层级/工作流策略的替代品。

1.3 强制执行 frontmatter 规则

.memory-bank/ 中的每个 Markdown 文件都必须包含 YAML frontmatter，且至少包含：

• description: ...
• status: draft|active|deprecated|archived

1.4 创建 .tasks/ 协议

为本次运行创建一个任务文件夹（选择一个新 ID）：

• .tasks/TASK-MB-INIT/

在其中创建：

• TASK-MB-INIT-S-00-orchestrator-plan.md — 计划要做的工作及使用的子 Agent

1.5 可选：Codex 配置文件预设

如果使用 Codex，请创建 .codex/config.toml 并配置以下配置文件：

• default：coding（gpt-5.2，high）
• 配置文件 deep-review：review（gpt-5.2，xhigh）

（如果仓库由多人共享，可以考虑将其保留在本地，或记录到 .memory-bank/runbooks/ 中。）

---

Step 2 — 选择场景

判定规则

• 如果仓库中有大量代码（src/、package.json、go.mod、Cargo.toml 等）→ Brownfield（Step 3B）。
• 如果仓库基本为空，且有 prd.md → Greenfield（Step 3A）；如果项目原则尚未获批或仅部分获批，建议先运行 /constitution，再运行 /write-prd。
• 如果仓库基本为空，且只有一个想法或粗略概念 → 可先运行 Analysis：想法尚未成形时运行 /analysis、/brainstorm，再运行 /brief；仅当项目原则尚未达到 ratified|partial 状态时，才在 /write-prd 之前运行 /constitution。
• 如果两者都有：按 Brownfield + PRD 增量 处理（Step 3B）。
• 如果仓库为空/新建，且没有 prd.md → 仅骨架（Step 3C）。

将场景记录在：

• .tasks/TASK-MB-INIT/TASK-MB-INIT-S-00-orchestrator-plan.md

---

Step 3A — Greenfield 工作流（PRD → Memory Bank）

3A.1 编写澄清后的 PRD

• 如果项目原则仍为框架默认值/已跳过/缺失，请在 /write-prd 之前运行 /constitution。如果原则已获批或部分获批，则直接继续运行 /write-prd。如果 .memory-bank/analysis/product-brief.md 存在，/constitution 会读取该文件，并在每轮提出最多 5 个与上下文相关的治理问题。
• 如果用户明确跳过 /constitution，则按框架默认/已跳过的原则继续，并注明之后仍可批准这些原则。
• 运行 /write-prd，将产品简报 / PRD 文本与 Constitution 转换为 .memory-bank/prd.md。
• /write-prd 每轮最多提出 5 个有针对性的问题，以处理 PRD 层面的歧义。
• 如果 PRD 提到“使用 skills/tools/CLIs”，请先运行 /find-skills（项目已安装 → marketplace）。

如果用户暂时无法联系（“запуск и ушёл”）：

• 在 .protocols/PRD-BOOTSTRAP/decision-log.md 中记录 Open questions。
• 停止并等待（不要编造事实；在得到答复前，不要继续生成 EP/FT/task）。

如果用户明确要求使用 autonomous mode：

• 将不阻塞的问题记录为 Assumptions
• 仅在遇到阻塞问题时暂停（安全/合规/外部契约/数据丢失风险）
• /write-prd 完成后继续运行 /autonomous

3A.2 将 PRD 路由到 L1–L3

运行 /spec-init，根据 PRD/简报/现有规范证据，更新 .memory-bank/spec-index.md，将其作为轻量级 SDD 路由图；不要进行架构访谈，也不要编造权威规范。 然后运行 /prd，将 .memory-bank/prd.md 分解为产品、需求、史诗、功能、测试，并更新索引。 运行 /prd 后，始终运行 /spec-design。对于小型独立 T0/T1 功能，可记录最简骨架，并将不相关部分标记为 not_applicable；对于共享/T2/T3 关注点，则创建或更新所需的骨架 SDD 规范和 spec-index。这不是另一个强制的重型阶段：它不会创建任务，也不会设计功能级实现。/spec-improve FT-<NNN> 仍是骨架之后的功能级关卡。

/prd 负责：

• .memory-bank/product.md
• REQ-ID
• RTM 表，将 REQ → Epic → Feature → Test 对应起来
• .memory-bank/epics/EP-*.md
• .memory-bank/features/FT-*.md

每个生成的功能都必须包含：

• 用例
• 验收标准
• 失败模式 / 边缘情况
• 测试策略提示

状态策略：

• 在 Open questions 得到解决之前，EP/FT 的 frontmatter 默认设为 status: draft。
• 只有在验收标准和验证计划稳定后，才将状态提升为 status: active。
• /prd / mb-from-prd 不会创建任务；规范的规划路径为 /write-prd → /spec-init → /prd → /spec-design → /spec-improve FT-<NNN> → /prd-to-tasks FT-<NNN>。
• 仅在明确存在功能级阻塞问题时，才为功能添加 clarification_status: pending|blocked。

3A.3 任务规划（按功能逐项，不要“一次性处理所有内容”）

不要一次性为所有功能生成完整任务队列。

请改为：

1. 确保 .memory-bank/schemas/task.schema.json 和 .memory-bank/tasks/index.json 存在。
2. 对每个选定的功能，仅当该功能明确处于待处理或受阻状态时，使用 /clarify-feature FT-<NNN>。
3. 在 /prd 之后运行 /spec-design；对于简单的 T0/T1 范围，使用精简的骨干规范；对于共享/T2/T3 关注事项，使用更完整的骨干规范。
4. 运行 /spec-improve FT-<NNN>，然后运行 /prd-to-tasks FT-<NNN>，以生成：
   • .memory-bank/tasks/plans/IMPL-FT-<NNN>.md
   • 按 wave 分组的原子化 .memory-bank/tasks/TASK-*.task.json 记录，每条记录都必须包含 tier: T0|T1|T2|T3

任务路由只能通过 task.tier 确定；旧的 risk / risk.level 模型无效。

3A.4 识别关键概念并创建支持文档

对于每个非平凡概念，都要创建支持文档，便于之后快速重新加载相关信息：

• 默认 / 兼容路径：
  • .memory-bank/architecture/<concept>.md（是什么 / 为什么）
  • .memory-bank/guides/<concept>.md（如何做）
• 在有助于明确事实来源时，添加由规范驱动的支持文档：
  • .memory-bank/tech-specs/...
  • .memory-bank/contracts/...
  • .memory-bank/domains/...
  • .memory-bank/states/...
  • .memory-bank/adrs/...
  • .memory-bank/runbooks/...
  • .memory-bank/testing/...

规则：

• 经典的双文档仍然有效且有用
• 由规范驱动的文档是补充内容，默认不取代经典文档
• 创建新规范前，先通过 .memory-bank/spec-index.md 检查现有规范
• 如果已有更详尽的文档，请从 .memory-bank/spec-index.md 和相关概念文档中链接到它们

3A.5 更新索引

更新 .memory-bank/index.md，添加指向所有已创建文档的注释链接。

---

第 3B 步 — 棕地工作流（仓库 → Memory Bank）

3B.1 启动扫描仓库的子 Agent（并行）

新建任务文件夹：

• .tasks/TASK-MB-MAP/

并行启动最多 5 个职责范围互不重叠的子 Agent：

1. S-01：构建/工具链（包管理器、脚本、CI）
2. S-02：后端/服务
3. S-03：前端/UI
4. S-04：数据层（数据库、迁移、架构）
5. S-05：测试 + 质量门禁

每个子 Agent 都必须：

• 验证其文件 glob 目标存在（“智能调用”）
• 使用以下命名规则，将详细报告写入 .tasks/TASK-MB-MAP/： TASK-MB-MAP-S-0X-final-report-<code|docs>-YY.md
• 返回 5–10 行摘要 + 文件列表

以 ./agents/shared-repo-scanner.md 作为基础提示词，但要限定扫描范围。

3B.2 根据报告综合构建 Memory Bank

使用 .tasks/TASK-MB-MAP/ 中的报告，填写：

• .memory-bank/product.md — 系统当前的实际情况
• .memory-bank/architecture/ — C4 L1–L3 概览 + 关键不变量
• .memory-bank/spec-index.md / .memory-bank/invariants.md / .memory-bank/glossary.md — 若证据支持明确的规范性路由
• .memory-bank/runbooks/ — 设置、开发、测试、部署
• .memory-bank/contracts/ — API/事件契约
• .memory-bank/states/ — 代码或工作流中可见的生命周期/状态规则
• .memory-bank/testing/index.md — 标准门禁 + 验证说明
• .memory-bank/index.md — 注释链接

无 PRD 规则（不可协商）：如果没有 prd.md，则不得创建或填充：

• .memory-bank/epics/*
• .memory-bank/features/*
• 包含真实路线图任务的 .memory-bank/tasks/*.task.json

如果空的骨架文件/文件夹是由引导流程创建的，则允许保留。

仓库映射记录的是现状文档，而不是路线图规划。如果无法从代码/日志/测试中推导出某项信息，应将其记录为假设或待解问题。

3B.3 询问用户提供 PRD 增量

基线 MB 创建完成后：

• 请用户提供 prd.md，说明要更改／添加的内容
• 仅当项目原则尚未获批或仅部分获批时，才先运行 /constitution，然后针对现有基线按 /write-prd、/spec-init、/prd、/spec-design、/spec-improve FT-<NNN> 和 /prd-to-tasks FT-<NNN> 的风格进行分解

---

步骤 3C — 仅创建骨架的工作流（无 PRD、无代码）

当仓库是新建／空仓库，且没有可用的 prd.md 时：

3C.1 仅创建骨架

照常运行步骤 1——创建所有目录、根据模板创建核心文件、创建 AGENTS.md 和 CLAUDE.md 符号链接。

骨架提供了一个可随时填充的结构：product.md、requirements.md、tasks/index.json 等文件仍是草稿存根／占位符。 在无 PRD 模式下，tasks/index.json 必须为 { "version": 1, "tasks": [] }，且不得生成 TASK-001.task.json 或其他可执行任务记录。

3C.2 请求提供 PRD

创建骨架后，请用户提供 PRD：

"Memory Bank 骨架已创建。若要填入产品详情、史诗、功能、SDD 设计和任务记录，请提供 prd.md 文件（或粘贴需求文本）。你可以现在提供，也可以稍后提供——仅当项目原则尚未处于 ratified|partial 状态时，才先运行 /constitution，然后运行 /write-prd、/spec-init、/prd、/spec-design、/spec-improve FT-<NNN> 和 /prd-to-tasks FT-<NNN>。"

3C.3 等待或继续

• 如果用户现在提供 PRD → 继续执行步骤 3A（Greenfield 工作流）。
• 如果用户决定稍后提供 → 在此停止。此时骨架有效且可用。用户之后可以调用 $mb-from-prd 或 /prd 来填充 Memory Bank。
• 如果用户提供部分信息 → 通过 /brief 处理，然后仅当项目原则尚未处于 ratified|partial 状态时运行 /constitution，再运行 /write-prd；如果仍有 PRD 层面的阻碍，则停止。

注意：仅创建骨架的状态是有效的停止点。AGENTS.md + .memory-bank/index.md + MBB 规则足以让 Agent 开始浏览仓库。

---

步骤 4 — 混合模式（Claude ↔ Codex）

如果你使用的是 Claude Code，但希望获得 Codex 质量或长周期自主能力：

1. 使用 Claude 子 Agent 将扫描报告写入 .tasks/TASK-MB-MAP/。
2. 通过 shell 调用 Codex 来综合生成 Memory Bank：

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'Read .tasks/TASK-MB-MAP and build/refresh .memory-bank per MBB. Keep AGENTS.md short. Produce a summary and run a self-review.'

3. 然后运行 Codex 深度审查配置文件（或启动一个新的 Claude 会话），进行 5 位专家审查。

---

步骤 5 — 多专家审查循环（新上下文）

使用全新上下文的审查者（不要复用撰写者的上下文）：

• 架构师（C4 + 依赖关系）
• 范围分析师（REQ → 史诗 → 功能 → 任务覆盖情况）
• MBB 合规审查者（frontmatter、链接、原子性、duo）
• 计划审查者（任务记录质量、波次、关卡）
• 安全审查者（身份验证、敏感数据、OWASP 风险）
• 代码质量审查者（条件性审查：仅在存在代码时审查质量关卡、约定和热点）

使用 ./agents/shared-review-*.md 和 ./agents/shared-mb-reviewer.md 中的提示词。

规则：

• 如果任何审查者返回 REJECT → 修复 MB 并重复审查。
• 将审查者报告保存到 .tasks/TASK-MB-REVIEW/。

---

步骤 6 — 开始执行任务

评审关卡通过（APPROVE）后：

1. 从 .memory-bank/tasks/index.json 及其索引的 .task.json 记录中，选取优先级最高且已就绪的任务。如果索引为空，请停止，并针对选定的功能运行 /spec-design，然后运行 /spec-improve FT-<NNN> 和 /prd-to-tasks FT-<NNN>。 仅当该功能明确处于待处理／受阻状态时，才先运行 /clarify-feature FT-<NNN>。
2. 对该任务运行 mb-execute（计划 → 实施 → 质量关卡 → MB-SYNC）。
3. 根据 task.tier 分流：T0／T1 可使用 run.md 中的精简验证；T2／T3 必须运行 mb-verify 和 mb-red-verify。
4. 对于 T3，关闭任务前必须设置人工介入检查点，并附上回滚／恢复说明。
5. 重复执行，直到本轮完成或用户叫停。

如果预期模式是无人值守端到端执行：

• 不要在此处停留于手动循环
• 切换到生成的项目命令 /autonomous

如果未安装 mb-execute、mb-verify 或 mb-red-verify，请手动遵循其 SKILL.md。

---

完成定义

满足以下条件即表示完成：

• 存在简短的 AGENTS.md，并指向 .memory-bank/index.md。
• CLAUDE.md 是 AGENTS.md 的符号链接／副本。
• .memory-bank/ 至少包含：索引、MBB、产品和测试（PRD 存在前，需求可以保留为占位内容）。
• .memory-bank/constitution.md 存在，并且可使用 /constitution 更新指导原则。
• .tasks/ 包含带有命名和阶段 ID 的扫描／评审产物。
• Greenfield：根据 PRD 创建史诗／功能／任务记录。
• Brownfield：将代码仓库的现状映射到 MB，并向用户询问 PRD 差异（没有 PRD 时，不得臆造路线图实体）。
• 仅骨架：创建骨架，并向用户询问 PRD（可作为有效的停止点）。
• 多专家评审通过（APPROVE）——适用于 Greenfield／Brownfield；仅骨架情况跳过。
• 执行循环可用（mb-execute + mb-verify 可访问或已有文档说明；对于 T2／T3 任务，还需支持 mb-red-verify）。
• Autonomous 循环可用（已记录 /autonomous + /autopilot）。

---

此技能中的参考资料

• ./references/shared-structure-template.md
• ./agents/shared-repo-scanner.md
• ./agents/shared-mb-reviewer.md
• ./agents/shared-review-architect.md
• ./agents/shared-review-scope.md
• ./agents/shared-review-code.md
• ./agents/shared-review-plan.md
• ./agents/shared-review-security.md
• ./scripts/shared-init-mb.js（可选辅助工具）