Vibecoding Kit

Vibecoding Kit 让 coding agent 以更安全、可验证的方式工作。

默认体验叫 Vibe Guided。它是 Vibecoding Kit 的默认真实模式：让 agent 在写代码、排障、收口和处理 review feedback 时，先做轻量任务分流，再按风险选择最小合适流程，并在完成前给出验证证据。

你可以把它理解成一个受控 agent 沙盒：

• 你正常提需求。
• agent 先判断任务类型和风险。
• 小任务直接处理，完成前做最小验证。
• 不清楚或高风险的任务先确认目标、范围、验收和验证方式。
• bug 或失败先复现并定位根因，再修改。
• 交付或收口先看验证证据，再判断能否交付。
• 默认不会偷偷提交、推送、创建 PR、调用外部平台、派发 subagent 或执行隐藏任务。

层定位：这是治理层，不是 agent runtime

marker: governance_layer_not_agent_runtime

Vibecoding Kit 是 agent 的治理层（governance layer），不是 agent runtime。这条边界决定了它该做什么、不该做什么：

• 它不提供感知—决策—行动循环，不调度模型，不执行工具。
• 它不保存供模型自动调用的长期记忆；本地只保留需要显式创建、只读比对的流程账本，以及必须人工晋升的 learning observation，这些内容不会被自动注入模型上下文。
• 真正的推理与执行发生在宿主 agent（Codex / Cursor / Claude Code 等）里。
• Vibecoding Kit 的职责，是给宿主 agent 提供入口合同、风险分流、证据链和交付 gate。
• tools/vibe-runtime/ 里的 runtime 指本地只读的流程状态账本，不是执行引擎。

判断标准：一项能力如果需要模型推理、命令执行、网络调用或持久化调度，它属于宿主 agent，不属于 Vibecoding Kit。

快速开始

如果你只是把 Vibecoding Kit 安装到业务项目，优先使用 npx 从 npm 临时执行 CLI：

npx @jtf19/vibecoding-kit init --target ../my-project --platform cursor
npx @jtf19/vibecoding-kit doctor --root ../my-project

npx 会执行发布包里的 vibe 命令，不会把 Vibecoding Kit 写入目标项目的依赖。

平台参数：

| 平台 | 入口文件 | 命令参数 | | -------- | ------------------------------------ | --------------------- | | Claude | CLAUDE.md | --platform claude | | Cursor | AGENTS.md | --platform cursor | | Codex | AGENTS.md | --platform codex | | OpenCode | .vibecoding/adapters/opencode/ | --platform opencode | | Pi | .vibecoding/adapters/pi/ | --platform pi | | 全部 | CLAUDE.md + AGENTS.md + adapters | --platform all |

第一次安装建议先预览：

npx @jtf19/vibecoding-kit init --target ../my-project --platform all --dry-run

已有 CLAUDE.md 或 AGENTS.md 时，先看合并预览：

npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=preview

确认后追加 Vibecoding managed block：

npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=append

如果你正在维护本仓库或需要从源码运行，可以使用本地入口：

node bin/vibe.mjs init --target ../my-project --platform cursor
node bin/vibe.mjs doctor --root ../my-project

需要只读入口判断时，可以从 Vibecoding Kit 所在位置运行：

node tools/vibe-runtime/index.mjs workflow --start --prompt "帮我确认下一步" --json --root ../my-project

需要一屏上手、候选学习审查或长任务前 token 检查时，可以继续使用这些只读入口：

node tools/vibe-runtime/index.mjs onboarding --brief --json --root ../my-project
node tools/vibe-runtime/index.mjs learning --inbox --json --root ../my-project
node tools/vibe-runtime/index.mjs tokens --readiness-gate --intent implementation --json --root ../my-project

这条上手路径默认不创建 .vibecoding-state/，不运行隐藏任务，不写业务源码，也不做 git 写入。

怎么使用

安装后直接对 agent 提需求：

帮我实现这个小功能。
先定位这个 bug 的原因。
帮我确认这个分支能不能交付。

Vibe Guided 会让 agent 按任务风险选择最小合适流程：

| 场景 | agent 应该怎么做 | | --------------- | --------------------- | | 小任务 | 直接处理，完成前做最小验证 | | 新功能 / 重构 | 先确认目标、边界、验收和验证方式 | | bug / 失败 | 先复现并定位根因，再修改 | | 交付前检查 | 先看验证证据和风险，再判断能否交付 | | review feedback | 先分类，判断是否阻塞，再说明修复和验证路径 |

模式

安装后项目只有两个用户可见模式。选择结果只持久化在 .vibecoding/config.json 的 automation_profile；execution_profile、execution policy、interaction 等运行时值由所选模式派生，不写入 config，也不能单独作为执行授权。

Vibe Guided（automation_profile: "vibe-guided"）是默认模式：

• 先读取 .vibecoding/skills/using-vibecoding/SKILL.md，做轻量任务分流。
• 默认只展示当前 route、下一步人工动作、验证策略或证据缺口。
• 不把维护者 runtime stage 长表强塞给普通业务任务。
• 不声称已经执行 workflow skill，除非当前响应真的按该 skill 的目标、边界和 handoff 要求执行。
• 完成前先给验证证据，或明确说明无法验证。

Vibe Extended（automation_profile: "vibe-extended"）是显式升级模式：在 Vibe Guided 之上叠加严格 skill-first 可见路由和受控本地执行 gate。切换方式：

npx @jtf19/vibecoding-kit profile --root <project-root> --show
npx @jtf19/vibecoding-kit profile --root <project-root> --set vibe-extended --dry-run
npx @jtf19/vibecoding-kit profile --root <project-root> --set vibe-extended --confirm

vibe-extended 不会放宽下面的安全边界；它在 Vibe Guided 之上启用严格 skill-first 可见路由和受控本地执行能力。默认安装写入 vibe-guided，安装时可显式选择 vibe-extended；切换只更新 .vibecoding/config.json 的 automation_profile。执行能力的差异由 manual / controlled-local 运行时能力表达。迁移合同见 docs/profile-mode-migration.md，实验或维护者内部 gate 见 docs/maintainer-guide.md。

安全边界

默认边界：

• 不自动提交、push、创建 PR 或 merge。
• 不自动调用平台 API、MCP、外部网络或模型。
• 默认不派发真实 subagent；subagent 是受控可选（subagent_controlled_optin_v1）：只有用户明确 opt-in、brief 完整、边界清楚时才进入受控判断，且 runtime 仍不自动派发。
• 不自动运行隐藏测试或后台 daemon。
• 不默认写业务源码或 .vibecoding-state/。

需要更强动作时，必须由用户明确授权，并且保留可复验的证据。允许改源码、允许运行本地命令、本地 commit、push、PR、merge 是分开的权限，不会因为选择 Vibe Guided 或 Vibe Extended 就自动获得。

安装后结构

业务项目默认只保留轻量入口，复杂规则放到 .vibecoding/：

CLAUDE.md          # Claude 入口，按平台生成
AGENTS.md          # Cursor / Codex 入口，按平台生成
.vibecoding/
  VIBE-CODING.md   # 完整 Vibecoding 规则
  config.json      # 仅持久化 automation_profile
  skills/
  adapters/
  hooks/
  shared/          # profile 输入边界和 canonical mode matrix

docs/ 和 examples/ 默认不安装；需要时使用 --with-docs 安装到 .vibecoding/。

常用文档

| 你要做什么 | 入口 | | -------------------------------------- | --------------------------------------------- | | 快速试用和安全 recipe | docs/quick-recipes.md | | 用户指南 | docs/user-guide.md | | 安装说明 | docs/install.md | | 安装 CLI 参考 | tools/vibe-init/README.md、tools/vibe-doctor/README.md | | 插件打包 | tools/vibe-plugin-pack/README.md | | runtime 用户只读入口和维护者合同 | tools/vibe-runtime-check/README.md、tools/vibe-runtime/README.md（先读 User command surface） | | 团队交付最小闭环 | docs/team-adoption.md、docs/golden-path.md | | evidence 填写 | docs/evidence-authoring.md、docs/ci-evidence-onboarding.md | | ok=false 和 readiness 解读 | docs/readiness-interpretation.md、docs/readiness-troubleshooting.md | | 验收和发布 | docs/acceptance-checklist.md、docs/release-guide.md | | 安装体验路线 | docs/install-experience-roadmap.md | | 维护 runtime、profile、release/check 和内部路线 | docs/maintainer-guide.md、docs/runtime-roadmap.md、docs/runtime-contract.md |

Open source

• License: Apache-2.0, see LICENSE.
• Contributing guide: CONTRIBUTING.md.
• Security policy: SECURITY.md.
• Changelog: CHANGELOG.md.
• Architecture overview: docs/architecture.md.
• Development guide: docs/development.md.