VibeCoding / VibeCoding

隐喻：这是一场电影的完整拍摄过程。 Metaphor: This is a film shoot, from first setup to final cut.

导演不必亲自掌镜。导演的工作是：把想法写成剧本，把剧本交到演员手中，喊一声"Action"。 The director does not operate the camera. The director writes the script, hands it to the actor, and calls "Action."

然后坐下来，看演员在镜头前表演。 Then sits back, and watches the actor perform before the lens.

观众走进放映厅，审视银幕上的一切——只有被看见的东西，才能被评价；只有被评价的东西，才能被改进。 The audience enters the projection room and takes in everything on screen — nothing can be critiqued until it has been seen; nothing can be improved until it has been critiqued.

技术文档往往冰冷，但创作不该如此。这套体系用电影的逻辑包裹工程的严谨——既保证交付质量，又尊重每个创作者的热情与局限。 Technical documents tend to be cold, but creation should not be. This system wraps engineering rigor in the logic of filmmaking — ensuring delivery quality while respecting every creator's passion and limits.

---

剧本已经写好，现在来看看拍摄现场的文件柜

The script is written. Now let's look at the filing cabinet on set.

整个拍摄过程只需要理解五份核心文件。其余所有文件，都是为了让这五份文件更精准、更可靠。 The entire shoot requires understanding only five core files. Everything else exists to make these five more precise and reliable.

电影术语 / Film Term	文档 / Document	它做什么 / What it does
导演手册 / Director's handbook	director.md	定义这个镜头怎么拍，什么能做，什么不能碰 / Defines how the shot runs, what's allowed, what's not
分镜脚本 / Storyboard	iteration_*.md	每次迭代就是一个镜头，写清楚问题、期望、约束 / Each iteration is a shot: problem, expectation, constraints
语法手册 / Syntax manual	vibe_references/information.md	告诉演员（AI Agent）如何理解优先级和类型 / Tells the actor (AI Agent) how to read priorities and types
制片日志 / Production log	project_forward.md	每个镜头拍完，记录三个下一个可以做得更好的事，外加一条收敛警示 / After each shot, log three improvements plus one convergence warning
拍摄进度墙 / Progress wall	project_forward.md	自动积累的历史展望，一眼看清项目走了多远 / Auto-accumulated history; one glance shows how far the project has come

---

快速开始 / Quick Start

并非所有项目都是从同一个起点出发的。本体系提供两条路径： Not all projects start from the same point. This system offers two entry paths.

线路 / Pathway	起点 / Starting Point	第一步 / First Step
从零创建 / From scratch	你有一个想法，面前是空目录。创意画布（create_init.md）上的任意文字触发 AI 创意点火，AI 自动填写 create.md 建立初始架构。 / You have an idea and an empty directory. Any text on the creative canvas (create_init.md) triggers AI ignition; AI auto-fills create.md to establish the initial architecture.	打开 vibe_guides/create_init.md，随便写下你的想法 / Open vibe_guides/create_init.md and write down your idea
既有项目引入 / Existing project	你已有代码库，想建立协作规范。说出"建立 VibeCoding 文档体系"触发逆向注入，体系自动注入后，你需要回顾性书写 create.md 记录已有项目的创造思路。 / You have an existing codebase. Say "establish VibeCoding" to trigger reverse injection; after the system injects itself, write create.md retrospectively to capture the project's creative origins.	阅读并填写 director.md 的"当前项目约束" / Read and fill in the "Current Project Constraints" section of director.md

需要的关键文件： Key files you need:

线路 / Pathway	关键文件 / Key Files
从零创建 / From scratch	vibe_guides/create_init.md + director.md
既有项目引入 / Existing project	director.md + vibe_references/information.md + vibe_iteration/iteration_0.md

想要完整部署？ Want full deployment?

将以下核心文件复制到项目中，建立完整的四层架构： Copy the following core files into your project to establish the complete four-layer architecture:

文件 / File	用途 / Purpose
director.md	总指挥 / Supreme authority
project_forward.md	展望与收敛警示 / Forward & convergence warning spec
vibe_references/information.md	迭代元信息标准 / Iteration meta-information standard
vibe_iteration/iteration_0.md	协办案模板 / Iteration document template
vibe_guides/control.md	控制思想 / Control theory framework
vibe_references/audience.md	能观之道 / Observability guide

完整部署后，你将获得收敛警示、逆向注入、控制理论反馈框架等全部能力。 With full deployment, you gain access to convergence warnings, reverse injection, control theory feedback framework, and all other capabilities.

---

机制说明 / Mechanisms

创意点火 / Creative Ignition

这是从零创建时发生的。你在 vibe_guides/create_init.md（一张空白画布）上随意写下想法，AI Agent 从中提取创意，自动填写 create.md，完成项目初始架构的建立。人类不写格式，AI 负责从混沌中提炼秩序。

This happens during creation from scratch. You write freely on vibe_guides/create_init.md (a blank canvas), and the AI Agent extracts your ideas to auto-fill create.md, establishing the project's initial architecture. Humans provide chaos; AI distills order.

逆向注入 / Reverse Injection

这是既有项目引入时发生的。你对已有项目说出"建立 VibeCoding 文档体系"，AI Agent 自动执行 vibe_guides/vibe_init.md 中的注入流程，在已有代码库上建立文档体系。然后你需要回顾性地书写 create.md，记录这个项目的创造初衷和思路。

This happens during existing project adoption. Say "establish the VibeCoding document system" to an existing project, and the AI Agent automatically executes the injection flow in vibe_guides/vibe_init.md, establishing the document system on top of existing code. You then write create.md retrospectively to capture how the project was originally created.

---

文档层次 / Document Hierarchy

如果你好奇这五份文件在体系中处于什么位置，以下是一个完整的四层架构概览。 If you're curious where these five files sit within the system, here's a complete four-layer architecture overview.

vibecoding/
├── README.md                          # 你现在正在阅读的文件
├── director.md                        # 总指挥 / Supreme authority
├── project_forward.md                 # 展望与收敛警示规范 & 展望历史 / Forward & convergence
├── vibe_iteration/
│   ├── create_init.md                 # 创意画布（从零创建时人类填写）
│   ├── iteration_0.md                 # 协办案标准模板（第零号）
│   └── create.md                      # AI 点火执行规范（从零创建时 AI 执行）
├── vibe_guides/
│   ├── control.md                     # 控制思想：状态空间与反馈策略
│   ├── vibe_init.md                   # 既有项目引入指南
│   └── iteration_workflow.md          # 完整迭代工作流
└── vibe_references/
    ├── information.md                 # 迭代元信息标准
    ├── audience.md                    # 能观之道
    └── doc_guide.md                   # 项目文档编写参考

加载顺序： Load order: director.md → information.md + project_forward.md → project_forward.md → iteration_*.md → 参考文件

这些文件在控制理论框架中的协作关系，参见 vibe_guides/control.md 第七节。 See vibe_guides/control.md Section 7 for their collaborative relationships within the control theory framework.

---

设计原则 / Design Principles

1. 文档驱动 / Documentation-driven 文档是意图的载体，代码是文档的实现。/ Documentation is the carrier of intent; code is the realization of documentation.

2. 分层自治 / Layered autonomy 核心权威极少变更，项目执行灵活多变。/ Core authority rarely changes; project execution remains flexible.

3. 显式优于隐式 / Explicit over implicit 所有约定都写在文档中。/ All agreements are written in documents.

4. 能观可验证 / Observable and verifiable 每个迭代都必须看得见、验得了。/ Every iteration must be observable and verifiable.

5. 项目必须收敛 / Projects must converge 通过 project_forward.md 的收敛警示机制，每次迭代后提醒审视项目是否该进入收敛阶段。 Through project_forward.md's convergence warning mechanism, remind after each iteration whether the project should enter convergence.

---

版本历史 / Changelog

版本 / Version	日期 / Date	说明 / Notes
v2.0	2026-05-21	体系化重构；融入电影拍摄隐喻与能控/能观理论；增加收敛警示机制；目录结构 vibe_* 化；create_init.md 创意画布 / Systematic restructure; film shoot metaphor; convergence warnings; vibe_* directories; create_init canvas

---

许可证 / License

本体系采用 GNU Affero General Public License v3.0 (AGPL-3.0)。 This system is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

VibeCoding Document System
Copyright (C) 2026

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

选择 AGPL-3.0 的原因：本体系是一套用于指导人类与 AI 协作的文档框架，AGPL 的传染性许可证确保任何基于本体系的衍生工作（包括通过网络交互使用的服务化改造）都必须开源，从而保护这套协作方法的公共性。 Why AGPL-3.0: This system is a documentation framework for guiding human-AI collaboration. AGPL's copyleft ensures that any derivative work (including service adaptations via network interaction) must be open-sourced, preserving the public nature of this collaborative methodology.