# Vibecoding 工程初始化说明

本文件是每个 vibecoding 工程的总说明书。初始化完成后，用户先补充 `01_init/` 资料，再执行 `codex` 或 `workbuddy` 初始化 / 刷新上下文；后续开发应先读取 `01_init/`、`06_catalog/` 和 `codes/` 的当前状态，再按“计划 -> 任务 -> 开发 -> 测试 -> 归档 -> 日志 -> 关闭”的闭环执行。每个命令结束后都会自动检查 Git，并提交本命令产生的改动。

## 1. 工程目标

vibecoding 工程用于把用户的原始想法、业务资料、项目相关人员信息、项目背景和代码执行过程沉淀成可追踪的开发体系。

- 上下文稳定：用户资料和项目资料统一放在 `01_init/`。
- 执行可控：每个需求先生成计划书和任务书，再进入代码修改。
- 过程可追溯：每次需求都在 `04_test/`、`05_archive/`、`06_catalog/` 留下同名记录。

## 2. 目录结构

```text
project-root/
├── 01_init/        # 项目初始化资料、用户资料、背景说明、图片、数据、链接和外部说明书
├── 02_plan/        # 需求计划书，每个需求一个计划文件
├── 03_task/        # 执行任务书，与计划书同名
├── 04_test/        # 测试资料目录，每个需求一个同名子目录
├── 05_archive/     # 归档资料目录，每个需求一个同名子目录
├── 06_catalog/     # 项目进度目录和需求执行日志
└── codes/          # 项目代码目录；存放所选工程项目代码，也可放用户已有旧项目代码
```

用户工程目录中不应包含 `.vibe/` 或 `scripts/`。模板属于 `vibecoding-cli` skill 包内部资产，由 agent 在需要时引用。

## 3. `01_init/` 资料规范

- `user.md`：项目相关人员信息，只填写姓名、项目角色、职责、可确认事项和项目相关背景。
- `description.md`：项目背景模板，填写业务目标、产品定位、目标用户、核心功能、非功能要求。
- `project-type.md`：项目类型配置，记录仓库地址、运行命令、测试命令、构建命令、环境要求和风险说明。
- `requirement-input-template.docx`：首选业务需求输入模板，用户按表格填写后可传给 `plan`、`plan-task` 或 `flow`。
- `requirement-input-template.md`：Markdown 备选模板，字段与 Word 模板一致。
- `command-reference.md`：命令体系说明。
- `readme.txt`：本工程说明书，不应删除。

其它会影响开发判断的资料也可以放入 `01_init/`，例如已填写的业务需求文档、截图、设计图、数据表、接口说明、竞品链接、会议纪要、业务规则、验收标准等。

建议新增资料时使用清晰的 ASCII 文件名，例如 `api-payment.md`、`design-home.png`、`rules-permission.md`。

## 4. 旧项目接入

如果用户已经有旧项目代码，建议放在：

```text
codes/
└── old-project/
```

如果旧项目本身已经是 Git 仓库，不要删除其内容。后续执行 `codex` 或 `workbuddy` 时，agent 应扫描 `codes/` 下现有代码结构、README、package 文件、环境变量样例和配置文件，再生成上下文。

## 5. 快速初始化原则

`init` 只做快速初始化：

- 先让用户选择工程项目。
- 创建或复制用户可见工作流目录。
- 创建或保留 `codes/`。
- 根据所选工程项目配置拉取工程代码到 `codes/<destination>/`。
- 初始化或复用 Git，并按 `vibecoding-cli init <YYYY-MM-DD HH:mm>` 提交本次初始化改动。
- 输出安装、启动、测试、构建、预览和验证命令，作为后续提示。

初始化阶段禁止执行：

- 安装依赖。
- 启动开发服务或后台进程。
- 运行项目代码。
- 运行测试、lint、构建、预览。
- 打开浏览器做验证。
- 执行数据库迁移、seed、Docker build 或部署命令。

这些操作只能在用户明确要求启动、运行项目、测试、构建或开发时再执行。

## 6. 标准闭环

初始化资料补充完成后，先刷新上下文：

```text
vibecoding-cli codex
vibecoding-cli workbuddy
```

需要把项目跑起来时，使用：

```text
vibecoding-cli start
```

`start` 会读取 `01_init/project-type.md` 和 `codes/` 中的项目描述、README、`package.json` 或框架配置，确定真实启动命令。前端、3D、海洋可视化项目启动后必须输出 `访问链接`，用户点击链接在浏览器查看；后端项目输出 API 地址、端口或健康检查地址。

后续需求建议从已填写的业务需求文档开始，例如：

```text
vibecoding-cli plan 业务需求文档.docx
vibecoding-cli plan-task 业务需求文档.docx
vibecoding-cli flow 业务需求文档.docx
```

每个需求建议使用同一个 ID 串联产物：

```text
02_plan/<id>.md
03_task/<id>.md
04_test/<id>/
05_archive/<id>/
06_catalog/<id>.md
```

文件名和目录名使用 ASCII；中文写在 Markdown 标题和正文中。

## 7. 输出规范

每次命令执行完成后，agent 对用户的回复必须简洁，只保留关键信息：

```text
本次命令：vibecoding-cli <command> <args>
执行结果：完成 / 部分完成 / 已阻塞
关键产物：<path>
访问链接：<URL，仅 start 启动前端时输出>
Git提交：<hash / 无变更，未提交 / 未提交（原因）>
下一步命令：vibecoding-cli <next-command> <args>
```

每次命令结束后，agent 必须只提交本命令产生的改动，提交信息使用 `vibecoding-cli <命令> <YYYY-MM-DD HH:mm>`。没有变更时不创建空提交，输出 `Git提交：无变更，未提交`。如果测试没有执行，必须用一句话说明原因。不要输出长日志、完整文件内容或大量文件列表，除非用户明确要求。
