vibecode-pro-max-kit：给 AI 编程项目补上规格、记忆和多 Agent 协作

用 AI 写代码最容易失控的三个场景：上下文被截断、计划散落在聊天记录里、决策没有留下痕迹。每次改需求，都得重新解释整个项目。

vibecode-pro-max-kit 解决的是流程问题：把 AI coding agent 变成 spec-driven engineering team。先写规格，再计划，再执行，每一步都留下可审计的记录。它不是聊天框架，也不替代 CI/CD，只做一件事：让 AI 编程的决策过程可追溯。

---

它解决什么问题

上下文流失：长对话被 compaction 截断，设计决策、边界条件、排障思路都没了。下次改需求要么重新解释，要么靠 AI 瞎猜。

计划和决策不留痕迹：聊天的 Markdown 导出不是结构化文档。团队成员 review 时看不到历史，不知道为什么选这个方案、排除了哪些选项。

多 agent 协作成本高：一个任务拆成多步，每步交给不同 agent，交接靠模糊的自然语言描述。谁负责哪一步、输出格式是什么、验收标准在哪，都得人工盯着。

这三件事叠加，AI 编程就变成“每次都像第一次”。vibecode-pro-max-kit 把它们收进一个 harness：spec 在前、plan 在中间、execution 有检查点、过程有记忆。

---

安装流程与安全审计

安装命令

README 给的是远程 shell 安装：

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

安装完成后，在 Claude Code 里运行 vc-setup；Codex 用户按 README 的提示使用 /vc-setup。它会创建 process/ 目录并初始化配置。

写入文件清单

当前 README 把安装描述为 non-destructive：不会清空现有 .claude/skills/、.claude/agents/、process/ 或 settings.json，只写入或更新 kit-owned 文件。它仍会在项目里放入这些目录和文件：

路径	内容
.claude/agents	Claude Code 专用 agent 定义，当前 README 写 15 个
.claude/skills	Claude Code 专用 skill 定义，当前 README 写 33 个
.claude/hooks	生命周期 hooks，当前 README 写 10 个
.codex/agents	给 Codex 使用的 mirrored agents
.agents/skills	指向 .claude/skills 的 symlink，用于 Codex discovery
CLAUDE.md	Claude Code orchestrator 与 routing rules
AGENTS.md	跨工具 agent 与 skill registry
process/	计划生命周期和项目记忆目录

README 还说明：已有配置会备份到 .vibecode-backup/，已有 CLAUDE.md 会备份为 CLAUDE.md.pre-vibecode，已有 process/ 不由安装脚本直接迁移，而是由 vc-setup / vc-update 交互处理。

安全审计要点

不要在生产仓库直接 curl | bash。即使 README 声称安装是 non-destructive，远程 shell 脚本仍然需要审计，因为它会写入 .claude/、.codex/、CLAUDE.md、AGENTS.md 等敏感路径。

建议的第一次试用流程：

1. fork 或 copy 一个非生产项目
2. 在 fork 里跑安装
3. git diff 检查写入的文件
4. 确认没有意料外的配置修改后再考虑迁移

安装脚本的备份机制是否适合你的仓库，需要自己验证。尤其是已有自定义 vc- 前缀 skill 或 agent 的项目，要按 README 的 caveat 额外检查。

这里的“不会覆盖”也不要理解成“没有风险”。它降低的是误删已有目录的概率，不等于你可以跳过供应链审计、权限隔离和回滚准备。对团队项目来说，最小安全动作仍然是：先读脚本，再在副本里跑，再让 reviewer 看 diff。

---

核心概念：spec-driven workflow

Spec Kit 背景

vibecode-pro-max-kit 的核心理念来自 Spec Kit 一类 spec-driven development（SDD）工作流。Spec Kit 的流程是：先写规格，再细化成计划，再拆成任务，最后执行。

每个阶段生成一个 Markdown artifact，为下一阶段提供结构化上下文：

阶段	输入	输出
Spec	需求描述	规格文档（边界、约束、验收标准）
Plan	规格文档	实施计划（步骤、责任人、依赖）
Tasks	实施计划	任务清单（具体、可验收）
Implement	任务清单	代码变更 + 过程记录

这个流程不新鲜，但 vibecode-pro-max-kit 把它“装进项目”：agents、skills、hooks 都围绕这个流程设计。

计划生命周期

当前 README 强调 RIPER-5 plan-first workflow，并把流程写成 7 个 gated phases：

阶段	做什么	输出产物
Research	收集背景、确认边界	research artifact
Spec	写清用户故事和需求边界	spec artifact
Innovate	比较方案、做取舍判断	alternatives / decision notes
Plan	细化步骤、分配责任和验证方式	plan artifact
Validate	在执行前验证计划和风险	validation notes
Execute	按任务执行、记录过程	code changes + execution notes
Update-Process	更新记忆、清理过时记录	process / context 更新

每个阶段需要显式批准才能推进。这是防止 AI 跑偏的关键：human 在检查点介入，确认方向正确再放行。

agents 与 skills

README 当前写的是 15 agents、33 skills、10 hooks。这个数字是 2026-06-23 核验时的官方 README 口径，会随仓库更新，不应该写成永久定数。

skills 结构与 Codex Skills、Claude Code skills 一致：每个 skill 有 SKILL.md（instructions），可选 scripts/、references/、assets/。skill 可以被显式调用，也可以在匹配边界内被隐式触发。

另外两个概念：

• context groups：按主题或功能组织的上下文块，避免每次加载全项目
• feature folders：按功能模块组织文件，每个 folder 有自己的 spec 和 process

---

安全机制详解

README 列了几类值得关注的安全和流程机制：

机制	作用	触发时机
privacy guardrails	阻止敏感信息进入 process 或输出	agent 输出和流程更新前
gated phases	阻止 agent 直接跳到写代码	Research 到 Update-Process 的阶段推进
check loops	让执行过程能自我检查和回到计划	执行和验证阶段
deviation protocol	记录偏离原计划的行为	plan 被修改或执行偏离时
high-risk evidence pack	高风险决策需要额外证据	某些判断触发阈值时

这些机制让 AI 不容易在无人监督下做高风险决策。但它们依赖 hooks 和配置正确运行。如果 hooks 被禁用、权限过宽，或者团队没有审查 process/，机制仍然可能失效。

---

适用场景判断表

场景	是否适合	原因
长期维护项目	适合	记忆沉淀在 process/，计划可审计
多人审阅	适合	决策留痕、偏离可追溯
复杂需求	适合	多 agent 协作、分阶段细化
容易丢上下文	适合	spec-driven 结构化对话
一次性脚本	不太适合	流程 overhead 过大
小修小补	不太适合	引入 harness 的成本高于收益
已有成熟工程流程	谨慎	可能与现有 CI/CD/review 流程冲突
不想引入外部 harness	不适合	README、AGENTS.md、CLAUDE.md 和 process 会改变仓库结构

判断核心：流程 overhead 是否值得。长期、复杂、多人协作的项目，overhead 换来可审计性和协作效率。短期、简单、单人的项目，overhead 就是纯成本。

---

与 Spec Kit、Codex Skills、Claude Code 的关系

Spec Kit：定义 SDD（spec-driven development）的背景和流程框架。概念层，不绑定具体 agent。

Codex Skills：OpenAI 的 skill 目录结构：SKILL.md + scripts/ + references/。它把 instructions、resources、scripts 打包成可复用工作流。

Claude Code skills：结构类似，SKILL.md + 支持文件。它把 skill 当成复用流程单元，可显式或隐式调用。

vibecode-pro-max-kit：把上述思路装进项目。它不是替代 Spec Kit，而是把 spec-driven 流程变成可执行的 agents + skills + hooks，同时兼容 Claude Code 和 Codex 的项目配置。

迁移成本：如果项目已有 .claude/agents、.claude/skills、CLAUDE.md 或 AGENTS.md，必须评估 diff，确认没有丢失自己的定制配置。

---

第一次试用流程

按 README 建议，第一次试用在非生产项目：

步骤 1：fork 或 copy 非生产项目

不要直接在主仓库操作。fork 仓库或 copy 一个本地测试目录。

步骤 2：运行安装命令

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

步骤 3：运行 vc-setup

在 Claude Code 里执行 vc-setup；在 Codex 里按 README 使用 /vc-setup。它会创建 process/ 目录并初始化配置。

步骤 4：检查文件写入

git status
git diff .claude/ .codex/ .agents/ CLAUDE.md AGENTS.md process/

确认写入的文件符合预期。

步骤 5：尝试第一个 spec-driven workflow

给 agent 一个简单需求，比如“添加一个日志打印函数”。观察 Research → Spec → Innovate → Plan → Validate → Execute → Update-Process 的过程，在每个阶段确认批准机制是否触发。

步骤 6：验收

看到 process/ 目录有产物、CLAUDE.md / AGENTS.md 的变更可理解、hooks 和 agents 没有报错，再考虑迁移到真实项目。

---

下一步与延伸阅读

已发布的相关文章：

• OpenClaw 多 agent 路由实践
• Claude Code workflow 完整指南
• AI agent 记忆机制解析

系列后续内容：

• 多 agent 协作排障清单（后续会单独写）
• spec-driven 项目实战案例（后续会单独写）