Vibe Coding Production Kit

像工程团队一样借助 AI 构建软件，而不是像进行一次聊天会话那样编码。

Vibe Coding Production Kit（VCP） 是一套具有生产工程思维的操作系统，也是用于 AI 辅助软件开发、零运行时依赖的 CLI。它将模糊的“vibe coding”转变为可重复执行的工程生命周期，围绕规格说明、架构、边界明确的任务、仓库原生 Agent 规则、就绪门禁、安全性、验证证据、独立审查、安全更新和恢复机制构建。

它不绑定任何模型，可与 Codex、Claude Code、Cursor、GitHub Copilot 及其他编程 Agent 等工具配合使用。

阿拉伯语文档：README.ar.md

直接运行已发布的 npm 包，无需全局安装：

npx vibe-coding-production init . --agent all --stack auto --yes

或者指定另一个仓库：

npx vibe-coding-production init ./my-app --agent claude --stack auto --yes

仅预览而不写入文件：

npx vibe-coding-production init . --agent all --stack auto --dry-run

通过 npm 包工具安装或调用时，该可执行程序也可使用 vcp 命令。

如果你有意运行仓库版本，而不是已发布的 npm 包：

npx --yes github:MoeEyani/Vibe-Coding-Production-Kit init . --agent all --stack auto --yes

该 CLI 要求 Node.js 22+，没有运行时依赖，且仅在仓库证据支持这一判断时自动检测 TypeScript、Python 和 Go。

初次使用？ 请按照端到端的 10 分钟快速入门 操作。

大多数 vibe coding 工作流优化的是让第一个 Demo 跑起来。VCP 优化的是第 100 个功能、第二位开发者、生产事故、安全审查、迁移、重构、升级，以及多年的维护工作。

随意的 vibe coding	Vibe Coding Production Kit
Prompt 是事实来源	仓库文档是事实来源
大型“构建这个应用”请求	小型、边界明确的任务契约
Agent 立即开始编码	就绪检查 + 先规划后编码门禁
“测试应该通过”	已执行的验证证据
同一个 Agent 既构建又评判	独立审查工作流
一次性复制模板	版本化生命周期状态 + 安全更新
通过覆盖/重新安装升级	基线、合并、迁移、回滚
希望生产环境一切正常	安全性、可观测性、发布/恢复思维

init
  ↓
task
  ↓
ready --stage plan
  ↓
context --mode plan
  ↓
plan
  ↓
ready --stage implement
  ↓
context --mode implement
  ↓
implement
  ↓
verify
  ↓
独立审查
  ↓
doctor
  ↓
release / observe

当有较新 VCP 版本可用时：

update --check
  ↓
update --dry-run
  ↓
如有冲突则解决冲突
  ↓
update
  ↓
doctor

安全的生命周期更新 —— v0.9

vcp init 现在会创建 .vcp/manifest.json 和持久化基线快照。仓库完成初始化后，VCP 会拒绝使用 init --force 替换该生命周期状态；升级必须通过更新引擎进行。

检查版本状态：

vcp update . --check
vcp update . --check --json

在不写入项目文件的情况下，预览完整迁移计划：

审阅计划后应用：

恢复最新的安全恢复点：

在不删除本地内容的情况下，取消跟踪或重新跟踪一个由 VCP 管理的文件：

vcp manage ignore AGENTS.md
vcp manage track AGENTS.md

更新引擎使用：

• 持久化基线哈希和快照；
• managed、generated 和 preserve 所有权策略；
• 针对独立修改的受限三方合并；
• 在重叠修改时显式报告 CONFLICT，而非进行猜测；
• 用于重命名/删除的版本化迁移声明；
• 在规划和变更前进行生命周期锁定；
• 路径遍历和符号链接保护；
• 事务状态、备份、应用后验证和自动回滚；
• 保守的回滚语义，而非假装不完整的历史备份是完整快照。

完整契约参见 docs/UPDATES.md，命令和选项参见 docs/CLI.md。

审计现有项目

只读的 doctor 会检查工程系统是否真正完成配置，而不只是被复制过：

npx vibe-coding-production doctor .

它会针对 Agent 指令、未解析的验证命令、事实来源文档、未修改的模板、CI、规划/审查工作流、清单兼容性、基线完整性和中断的更新事务，报告具体的 PASS / WARN / FAIL 结果。

可使用 --json 实现自动化，或使用 --strict 让警告返回非零状态。参见 docs/DOCTOR.md。

在编码前创建边界明确的任务

npx vibe-coding-production task accept-invite --title "接受邀请"

生成器会创建 docs/tasks/accept-invite.md，其中包含事实来源链接、验收标准、范围边界、安全/隐私问题、失败模式、可观测性、测试、发布/恢复、实现规划、审查检查项，以及实际在 AGENTS.md 中配置的验证命令。

参见 docs/TASK-PACKS.md。

在规划和实现前进行就绪检查

vcp ready accept-invite --stage plan
vcp ready accept-invite --stage implement

规划门禁要求具备真实的目标结果、可解析的事实来源、具体的验收标准和明确的范围。实现门禁还要求架构/数据/集成边界、领域不变量、安全/隐私、失败模式、可观测性、测试、发布/恢复及具体实现计划均已明确。

参见 docs/TASK-READINESS.md。

为 AI 的每个阶段构建正确上下文

vcp context accept-invite --mode plan

随着任务推进，可使用 --mode implement、review、security 或 release。使用可重复的 --include 标志仅添加受影响的实现文件。上下文包会拒绝逃逸出仓库的路径，并默认强制执行大小预算。

参见 docs/CONTEXT-PACKS.md。

将“我运行过测试”变成证据

预览将要执行的确切内容：

执行要求明确同意，并且任务已具备实现就绪状态：

vcp verify accept-invite --run \
  --output .vcp/evidence/accept-invite.json

命令会按顺序运行，并在首次失败后停止。证据会记录命令、状态、退出码、信号、超时状态和耗时；默认会特意避免持久化原始 stdout/stderr。

参见 docs/VERIFICATION-EVIDENCE.md。

从 examples/reference-saas-invite/ 开始，了解这一工作流如何成为具体的工程产物，而不是空白模板。

它建模了一个安全敏感的多租户邀请垂直切片，包含已完成的产品/领域/架构/数据工件、ADR、威胁模型、测试策略、边界明确的任务、分层代码，以及针对授权、租户边界、令牌哈希、过期、重放和电子邮件绑定的负路径测试。

cd examples/reference-saas-invite
npm test
npm run check

该示例会明确说明对于真实生产基础设施而言哪些内容仍未得到验证，而不会将一个 Demo 称为“生产就绪”。

不要让 AI 替你构建项目。要构建一套系统，让 AI 难以错误地构建你的项目。

人类负责意图、权衡、架构、风险接受和最终决策。AI 在明确约束内协助研究、规划、实现、测试、审查、文档编写和自动化。

想法
  -> 产品简报
  -> PRD + 验收标准
  -> 用户流程
  -> 领域模型
  -> 架构 + ADR
  -> 数据模型
  -> 威胁模型
  -> 测试策略
  -> Epic / 用户故事 / 边界明确的任务
  -> 就绪门禁
  -> 编码前规划
  -> 有边界的实现
  -> 验证证据
  -> 独立审查
  -> CI 门禁
  -> 发布 + 可观测性
  -> 安全的 VCP 生命周期更新
  -> 学习并更新事实来源

• AGENTS.md —— 面向编程 Agent 的仓库级规则。
• 产品模板 —— 产品简报、PRD、用户流程、验收标准。
• 架构模板 —— 领域模型、系统设计、数据模型、ADR。
• 安全模板 —— 在实现前进行威胁建模。
• 测试策略 —— 单元/集成/契约/E2E 测试决策框架。
• 交付系统 —— Definition of Ready、Definition of Done、任务/发布检查清单。
• vcp task —— 有边界、仓库原生的任务契约。
• vcp ready —— 分离的规划/实现就绪门禁。
• vcp context —— 有边界、按阶段划分的 AI 上下文包。
• vcp verify —— 显式执行和验证证据。
• vcp doctor —— 仓库/系统健康审计，避免给出具有误导性的魔法评分。
• vcp update —— 具备生命周期感知能力的安全更新，支持合并/迁移/恢复。
• Agent Prompt —— 探索、规划、实现、审查、安全、重构、发布审查。
• GitHub 工程规范 —— issue 模板、PR 模板、贡献指南、安全政策、验证工作流。
• 英文 README 及阿拉伯语指南。

按以下顺序填写事实来源文档

1. docs/product/PRODUCT-BRIEF.md
2. docs/product/PRD.md
3. docs/product/USER-FLOWS.md
4. docs/architecture/DOMAIN.md
5. docs/architecture/ARCHITECTURE.md
6. docs/architecture/DATA-MODEL.md
7. docs/security/THREAT-MODEL.md
8. docs/testing/TEST-STRATEGY.md

然后在 AGENTS.md 中使用真实的仓库命令进行定制，包括安装、格式化、lint、类型检查、单元/集成测试、构建和 E2E。

flowchart LR
    A[选择任务] --> B[阅读事实来源]
    B --> C[就绪检查：规划]
    C --> D[构建规划上下文]
    D --> E[不修改文件地制定计划]
    E --> F[就绪检查：实现]
    F --> G[实现边界明确的范围]
    G --> H[验证证据]
    H --> I[自审 diff]
    I --> J[独立审查]
    J --> K{质量门禁是否通过？}
    K -- 否 --> G
    K -- 是 --> L[合并 / 发布 / 观测]

.
├── AGENTS.md
├── README.md
├── README.ar.md
├── CONTRIBUTING.md
├── SECURITY.md
├── bin/
├── lib/
├── docs/
│   ├── 00-START-HERE.md
│   ├── QUICKSTART.md
│   ├── CLI.md
│   ├── UPDATES.md
│   ├── product/
│   ├── architecture/
│   ├── security/
│   ├── testing/
│   └── delivery/
├── prompts/
├── examples/
├── scripts/
└── .github/

1. 先有规格，再做实现。
2. 架构决策应被记录，而非埋没在聊天记录中。
3. 不允许大型、无边界的 Agent 任务。
4. 在信任边界处验证外部输入。
5. 授权应在服务端执行，并针对具体资源。
6. 模式变更应使用经过审查的迁移，并考虑回滚。
7. 测试应与行为同步添加，而不是拖到最后。
8. 构建者不能是唯一的审查者。
9. 在 CI 可用时，CI 是机械执行层面的事实来源。
10. 生产环境必须可观测、可恢复。
11. 生命周期升级必须经过规划且可逆；不得盲目重新复制模板。

一个好的 Agent 任务通常具备：

• 一个主要目标；
• 一组范围狭窄的受影响模块；
• 明确的验收标准；
• 已知的测试；
• 没有无关的重构；
• 足够小、可由人类理解的 diff。

如果一个任务需要长篇解释“既然你已经在这里了，不如顺便……”，那就应将其拆分。

该工具包有意避免将你锁定在某一家 AI 供应商上。请将通用规则保留在 AGENTS.md 中，只有在工具专用指令文件确有实际价值时才添加它们。

不要在多个 Agent 配置文件中重复编写相互冲突的规则。应优先采用单一事实来源和轻量适配器。

如果你想参与贡献，请参见 CONTRIBUTING.md。

MIT —— 可用于个人、商业和开源项目。

Vibe Coding Production Kit

Build with AI like an engineering team — not like a chat session.

Vibe Coding Production Kit (VCP) is a production-minded operating system and zero-runtime-dependency CLI for AI-assisted software development. It turns vague “vibe coding” into a repeatable engineering lifecycle built around specifications, architecture, bounded tasks, repository-native agent rules, readiness gates, security, verification evidence, independent review, safe updates, and recovery.

It is model-agnostic and works with tools such as Codex, Claude Code, Cursor, GitHub Copilot, and other coding agents.

Arabic documentation: README.ar.md

Run the published npm package directly — no global install required:

npx vibe-coding-production init . --agent all --stack auto --yes

Or target another repository:

npx vibe-coding-production init ./my-app --agent claude --stack auto --yes

Preview without writing:

npx vibe-coding-production init . --agent all --stack auto --dry-run

The executable is also available as vcp when installed or invoked through npm package tooling.

If you intentionally want to run the repository version instead of the published npm package:

npx --yes github:MoeEyani/Vibe-Coding-Production-Kit init . --agent all --stack auto --yes

The CLI requires Node.js 22+ , has no runtime dependencies , and auto-detects TypeScript, Python, and Go only when repository evidence supports that decision.

New here? Follow the end-to-end 10-minute Quickstart.

Most vibe-coding workflows optimize for getting the first demo working. VCP optimizes for the 100th feature, the second developer, production incidents, security reviews, migrations, refactors, upgrades, and years of maintenance.

Casual vibe coding	Vibe Coding Production Kit
Prompt is the source of truth	Repository docs are the source of truth
Large “build this app” requests	Small bounded task contracts
Agent starts coding immediately	Readiness + plan-before-code gates
“Tests should pass”	Executed verification evidence
Same agent builds and judges	Independent review workflow
Copy templates once	Versioned lifecycle state + safe updates
Overwrite/reinstall to upgrade	Baselines, merge, migrations, rollback
Hope production is okay	Security, observability, release/recovery thinking

init
  ↓
task
  ↓
ready --stage plan
  ↓
context --mode plan
  ↓
plan
  ↓
ready --stage implement
  ↓
context --mode implement
  ↓
implement
  ↓
verify
  ↓
independent review
  ↓
doctor
  ↓
release / observe

When a newer VCP version is available:

update --check
  ↓
update --dry-run
  ↓
resolve conflicts if any
  ↓
update
  ↓
doctor

Safe lifecycle updates — v0.9

vcp init now creates .vcp/manifest.json and persistent baseline snapshots. Once a repository is initialized, VCP refuses to replace that lifecycle state with init --force; upgrades go through the update engine.

Check version state:

vcp update . --check
vcp update . --check --json

Preview the full migration plan without writing project files:

Apply after reviewing the plan:

Recover the newest safe recovery point:

Detach or re-track one VCP-managed file without deleting local content:

vcp manage ignore AGENTS.md
vcp manage track AGENTS.md

The update engine uses:

• persistent baseline hashes and snapshots;
• managed, generated, and preserve ownership policies;
• bounded three-way merge for independent edits;
• explicit CONFLICT instead of guessing on overlaps;
• versioned migration declarations for renames/removals;
• lifecycle locking before planning and mutation;
• path traversal and symlink protections;
• transaction state, backups, post-apply verification, and automatic rollback;
• conservative rollback semantics instead of pretending partial historical backups are complete snapshots.

See docs/UPDATES.md for the full contract and docs/CLI.md for commands/options.

Audit an existing project

The read-only doctor checks whether the engineering system is actually configured—not merely copied:

npx vibe-coding-production doctor .

It reports concrete PASS / WARN / FAIL findings for agent instructions, unresolved verification commands, source-of-truth documents, untouched templates, CI, plan/review workflow, manifest compatibility, baseline integrity, and interrupted update transactions.

Use --json for automation or --strict to make warnings non-zero. See docs/DOCTOR.md.

Create a bounded task before coding

npx vibe-coding-production task accept-invite --title "Accept invitation"

The generator creates docs/tasks/accept-invite.md with source-of-truth links, acceptance criteria, scope boundaries, security/privacy questions, failure modes, observability, tests, rollout/recovery, implementation planning, review checks, and the verification commands actually configured in AGENTS.md.

See docs/TASK-PACKS.md.

Gate readiness before planning and implementation

vcp ready accept-invite --stage plan
vcp ready accept-invite --stage implement

The planning gate requires a real outcome, resolvable Source of Truth, concrete acceptance criteria, and explicit scope. The implementation gate additionally requires resolved architecture/data/integration boundaries, domain invariants, security/privacy, failure modes, observability, testing, rollout/recovery, and a concrete implementation plan.

See docs/TASK-READINESS.md.

Build the right context for each AI phase

vcp context accept-invite --mode plan

Use --mode implement, review, security, or release as the task progresses. Add only affected implementation files with repeatable --include flags. Context packs reject repository escapes and enforce a size budget by default.

See docs/CONTEXT-PACKS.md.

Turn “I ran the tests” into evidence

Preview exactly what would execute:

Execution requires explicit consent and an implementation-ready task:

vcp verify accept-invite --run \
  --output .vcp/evidence/accept-invite.json

Commands run sequentially and stop after the first failure. Evidence records command, status, exit code, signal, timeout state, and duration, while raw stdout/stderr is deliberately not persisted by default.

See docs/VERIFICATION-EVIDENCE.md.

Start with examples/reference-saas-invite/ to see the workflow as concrete engineering artifacts instead of blank templates.

It models a security-sensitive multi-tenant invitation vertical slice with completed product/domain/architecture/data artifacts, ADR, threat model, test strategy, bounded task, layered code, and negative-path tests for authorization, tenant boundaries, token hashing, expiry, replay, and email binding.

cd examples/reference-saas-invite
npm test
npm run check

The example explicitly documents what remains unproven for real production infrastructure instead of calling a demo “production-ready.”

Do not ask AI to build your project. Build a system that makes it difficult for AI to build your project incorrectly.

The human owns intent, trade-offs, architecture, risk acceptance, and final decisions. AI helps research, plan, implement, test, review, document, and automate — inside explicit constraints.

Idea
  -> Product brief
  -> PRD + acceptance criteria
  -> User flows
  -> Domain model
  -> Architecture + ADRs
  -> Data model
  -> Threat model
  -> Test strategy
  -> Epics / stories / bounded tasks
  -> Readiness gate
  -> Plan before code
  -> Bounded implementation
  -> Verification evidence
  -> Independent review
  -> CI gates
  -> Release + observability
  -> Safe VCP lifecycle updates
  -> Learn and update the source of truth

• AGENTS.md — repository-wide rules for coding agents.
• Product templates — product brief, PRD, user flows, acceptance criteria.
• Architecture templates — domain model, system design, data model, ADRs.
• Security template — threat modeling before implementation.
• Test strategy — unit/integration/contract/E2E decision framework.
• Delivery system — Definition of Ready, Definition of Done, task/release checklists.
• vcp task — bounded repository-native task contracts.
• vcp ready — separate plan/implementation readiness gates.
• vcp context — bounded phase-specific AI context packs.
• vcp verify — explicit execution and verification evidence.
• vcp doctor — repository/system health audit without a misleading magic score.
• vcp update — lifecycle-aware safe updates with merge/migrations/recovery.
• Agent prompts — discovery, planning, implementation, review, security, refactoring, release review.
• GitHub hygiene — issue templates, PR template, contributing guide, security policy, validation workflow.
• English README plus an Arabic guide.

Fill source-of-truth documents in this order

1. docs/product/PRODUCT-BRIEF.md
2. docs/product/PRD.md
3. docs/product/USER-FLOWS.md
4. docs/architecture/DOMAIN.md
5. docs/architecture/ARCHITECTURE.md
6. docs/architecture/DATA-MODEL.md
7. docs/security/THREAT-MODEL.md
8. docs/testing/TEST-STRATEGY.md

Then customize AGENTS.md with real repository commands for install, format, lint, typecheck, unit/integration tests, build, and E2E.

flowchart LR
    A[Select task] --> B[Read Source of Truth]
    B --> C[Readiness: plan]
    C --> D[Build plan context]
    D --> E[Plan without editing]
    E --> F[Readiness: implement]
    F --> G[Implement bounded scope]
    G --> H[Verification evidence]
    H --> I[Self-review diff]
    I --> J[Independent review]
    J --> K{Quality gates pass?}
    K -- No --> G
    K -- Yes --> L[Merge / release / observe]

Loading

.
├── AGENTS.md
├── README.md
├── README.ar.md
├── CONTRIBUTING.md
├── SECURITY.md
├── bin/
├── lib/
├── docs/
│   ├── 00-START-HERE.md
│   ├── QUICKSTART.md
│   ├── CLI.md
│   ├── UPDATES.md
│   ├── product/
│   ├── architecture/
│   ├── security/
│   ├── testing/
│   └── delivery/
├── prompts/
├── examples/
├── scripts/
└── .github/

1. Specs before implementation.
2. Architecture decisions are recorded, not buried in chat history.
3. No large unbounded agent tasks.
4. External input is validated at trust boundaries.
5. Authorization is server-side and resource-specific.
6. Schema changes use reviewed migrations and rollback thinking.
7. Tests are added with behavior, not postponed to the end.
8. The builder is not the only reviewer.
9. CI is the mechanical source of truth when CI is available.
10. Production must be observable and recoverable.
11. Lifecycle upgrades are planned and reversible; templates are not blindly recopied.

A good agent task normally has:

• one primary outcome;
• a narrow set of affected modules;
• explicit acceptance criteria;
• known tests;
• no unrelated refactor;
• a diff small enough for a human to understand.

If a task requires a long explanation of “and while you're there…”, split it.

The kit intentionally avoids locking you into one AI vendor. Keep universal rules in AGENTS.md, and add tool-specific instruction files only when they provide real value.

Do not duplicate conflicting rules across multiple agent configuration files. Prefer one source of truth and thin adapters.

See CONTRIBUTING.md if you want to help.

MIT — use it in personal, commercial, and open-source projects.