@jtf19/vibecoding-kit 0.1.0

package/docs/phase-1-implementation.md

@@ -0,0 +1,848 @@
+# Vibecoding Kit 第一阶段实践落地文档
+
+## 目标
+
+第一阶段的目标不是做完整的 agent OS，也不是复刻 `ECC`、`external reference`、`token-savior` 或 `distill`。
+
+第一阶段只做一个可安装、可触发、可维护的最小 vibecoding skill / plugin 核心。
+
+目标结果：
+
+1. Claude / Codex / Cursor 三个平台都能接入。
+2. 有统一的 vibecoding bootstrap。
+3. 有 5 到 8 个高质量 workflow skills。
+4. 有基础 session-start hook。
+5. 有清晰的目录结构和发布边界。
+6. 暂不引入大型 MCP、复杂 memory、完整 codebase index。
+
+## 第一阶段范围
+
+### 包含
+
+第一阶段包含以下能力：
+
+- 跨平台插件目录结构。
+- Claude、Codex、Cursor 的最小适配。
+- 统一入口说明文件。
+- vibecoding bootstrap skill。
+- 核心 workflow skills。
+- 基础 session-start hook。
+- 安装说明文档。
+- 最小人工验收流程。
+
+### 不包含
+
+第一阶段明确不做：
+
+- 完整 MCP server。
+- 跨会话 memory database。
+- 结构化代码索引。
+- 大规模 agents 编排。
+- 大量业务域 skills。
+- 自动生成 skill catalog。
+- 复杂 GUI / dashboard。
+- 多平台全覆盖。
+
+这些能力留到后续阶段。
+
+## 目录结构
+
+第一阶段建议落地为以下结构：
+
+```text
+vibe-coding-kit/
+  README.md
+  CLAUDE.md
+  AGENTS.md
+
+  skills/
+    using-vibecoding/
+      SKILL.md
+    vibe-planning/
+      SKILL.md
+    vibe-debugging/
+      SKILL.md
+    vibe-implementation/
+      SKILL.md
+    vibe-review/
+      SKILL.md
+    vibe-verification/
+      SKILL.md
+    vibe-context-compact/
+      SKILL.md
+
+  adapters/
+    claude/
+      plugin.json
+      settings.example.json
+      install.md
+    codex/
+      plugin.json
+      hooks.example.json
+      install.md
+    cursor/
+      plugin.json
+      hooks.example.json
+      install.md
+
+  hooks/
+    session-start/
+      README.md
+      session-start.md
+    post-tool-compact/
+      README.md
+
+  docs/
+    vibecoding-fork-analysis.md
+    phase-1-implementation.md
+    install-claude.md
+    install-codex.md
+    install-cursor.md
+    skill-authoring-guide.md
+    acceptance-checklist.md
+
+  examples/
+    claude-project/
+    codex-project/
+    cursor-project/
+```
+
+如果当前仓库还没有这些目录，不需要一次性全部创建。第一阶段可以先保证：
+
+```text
+skills/
+adapters/
+hooks/
+docs/
+examples/
+```
+
+这五个顶层目录存在即可。
+
+## 模块职责
+
+### `skills/`
+
+`skills/` 是第一阶段的核心资产。
+
+它不存放普通提示词，而是存放可复用、可触发、可迁移的工作流能力。
+
+每个 skill 应该回答四个问题：
+
+1. 什么时候使用。
+2. 输入是什么。
+3. 处理过程是什么。
+4. 输出是什么。
+
+第一阶段不追求数量，优先保证质量。
+
+建议控制在 6 个核心 skill：
+
+```text
+using-vibecoding
+vibe-planning
+vibe-debugging
+vibe-implementation
+vibe-review
+vibe-verification
+vibe-context-compact
+```
+
+### `adapters/`
+
+`adapters/` 用来隔离不同平台差异。
+
+不同平台对 skill、plugin、hook、instruction file 的识别方式不同，因此不要把平台差异散落在 `skills/` 内部。
+
+职责边界：
+
+- `skills/` 只描述通用工作流。
+- `adapters/` 负责让这些工作流在 Claude / Codex / Cursor 中可被发现和加载。
+
+第一阶段只做三个平台：
+
+```text
+adapters/claude
+adapters/codex
+adapters/cursor
+```
+
+### `hooks/`
+
+第一阶段的 hook 只做“会话入口引导”，不要急着做复杂自动化。
+
+建议先保留两个 hook 主题：
+
+```text
+session-start
+post-tool-compact
+```
+
+其中：
+
+- `session-start` 第一阶段必须做。
+- `post-tool-compact` 第一阶段只写说明和预留，不必实现完整压缩工具。
+
+### `docs/`
+
+`docs/` 负责沉淀项目设计、安装、验收和协作规范。
+
+第一阶段文档建议至少包含：
+
+- `phase-1-implementation.md`：当前文档。
+- `install-claude.md`：Claude 安装方式。
+- `install-codex.md`：Codex 安装方式。
+- `install-cursor.md`：Cursor 安装方式。
+- `skill-authoring-guide.md`：skill 编写规范。
+- `acceptance-checklist.md`：验收清单。
+
+### `examples/`
+
+`examples/` 用来放不同平台的最小可运行样例。
+
+它不是测试目录，而是让用户能快速理解“装完之后应该长什么样”。
+
+## 第一阶段核心 skills
+
+### 1. `using-vibecoding`
+
+定位：统一入口 / bootstrap。
+
+作用：告诉 agent 当前项目如何使用 vibecoding skills。
+
+触发时机：
+
+- 每个新会话开始时。
+- 用户说“开始做功能”、“规划一下”、“修 bug”、“review 一下”时。
+- agent 准备进入开发任务前。
+
+职责：
+
+- 识别当前任务类型。
+- 选择合适的 workflow skill。
+- 约束 agent 不要跳过规划、验证、复盘。
+- 定义 skill 优先级。
+
+建议内容结构：
+
+```text
+---
+name: using-vibecoding
+description: Use when starting any development task to select the right vibecoding workflow.
+---
+
+## 目标
+
+## 使用规则
+
+## skill 选择表
+
+## 平台适配说明
+
+## 禁止事项
+
+## 输出要求
+```
+
+skill 选择表建议：
+
+| 用户意图 | 使用 skill |
+| --- | --- |
+| 想做新功能 | `vibe-brainstorming` -> `vibe-planning` -> `vibe-writing-plans` -> `vibe-test-driven-development` -> `vibe-executing-plans` -> `vibe-verification-before-completion` -> `vibe-finishing-a-development-branch` |
+| 明确小任务 | `vibe-test-driven-development` -> `vibe-implementation` -> `vibe-verification-before-completion` |
+| 修 bug | `vibe-systematic-debugging` -> `vibe-test-driven-development` -> `vibe-implementation` -> `vibe-verification-before-completion` |
+| 要求 review | `vibe-review` |
+| 上下文太长 / 输出太乱 | `vibe-context-compact` |
+| 不确定怎么做 | `vibe-planning` |
+
+### 2. `vibe-planning`
+
+定位：需求澄清和落地计划。
+
+适用场景：
+
+- 新功能。
+- 重构。
+- 模块边界不清晰。
+- 用户只给了模糊目标。
+- 需要在多个方案中取舍。
+
+输入：
+
+- 用户目标。
+- 当前项目结构。
+- 约束条件。
+- 参考项目或现有代码。
+
+输出：
+
+- 目标定义。
+- 范围边界。
+- 模块拆分。
+- 数据流 / 状态流。
+- 实施顺序。
+- 验收标准。
+
+禁止：
+
+- 一上来就写代码。
+- 用空泛步骤代替模块边界。
+- 没有验收标准就进入实现。
+
+### 3. `vibe-debugging`
+
+定位：系统化排查问题。
+
+适用场景：
+
+- bug。
+- 构建失败。
+- 测试失败。
+- 运行结果和预期不一致。
+- 用户说“为什么不工作”。
+
+处理顺序：
+
+1. 明确现象。
+2. 找到稳定复现方式。
+3. 缩小影响范围。
+4. 定位状态变化点。
+5. 做最小修复。
+6. 验证修复。
+
+输出：
+
+- 问题现象。
+- 根因判断。
+- 修改范围。
+- 验证方式。
+
+禁止：
+
+- 无证据猜测。
+- 同时改多个变量。
+- 未复现就大范围重构。
+
+### 4. `vibe-implementation`
+
+定位：按计划实现功能。
+
+适用场景：
+
+- 已有明确计划。
+- 小型明确任务。
+- 用户要求直接实现。
+
+处理原则：
+
+- 保持修改范围小。
+- 优先复用现有项目结构。
+- 不引入无关依赖。
+- 不顺手重构无关模块。
+- 不覆盖用户已有改动。
+
+输出：
+
+- 完成的功能点。
+- 修改的主要文件。
+- 是否有未完成项。
+- 是否需要用户确认。
+
+### 5. `vibe-review`
+
+定位：质量审查。
+
+适用场景：
+
+- 用户要求 review。
+- 准备合并。
+- 完成较大改动后。
+
+审查维度：
+
+- 需求是否满足。
+- 模块边界是否清晰。
+- 状态流是否合理。
+- 错误处理是否完整。
+- 是否有过度设计。
+- 是否引入安全风险。
+- 是否破坏平台兼容。
+
+输出优先级：
+
+1. 阻塞问题。
+2. 高风险问题。
+3. 中低风险改进。
+4. 可选建议。
+
+禁止：
+
+- 为了显得全面而堆砌无关建议。
+- 只讲代码风格，不讲行为风险。
+- 没有证据就断言问题。
+
+### 6. `vibe-verification`
+
+定位：完成前验证。
+
+适用场景：
+
+- 实现完成后。
+- 修复完成后。
+- 准备交付给用户前。
+
+验证内容：
+
+- 是否满足用户目标。
+- 是否跑过必要检查。
+- 是否有 lint / test / build 问题。
+- 是否有未处理的边界情况。
+- 是否有改动范围外的风险。
+
+输出：
+
+- 已验证项。
+- 未验证项。
+- 阻塞项。
+- 可交付判断。
+
+### 7. `vibe-context-compact`
+
+定位：上下文压缩和任务交接。
+
+适用场景：
+
+- 会话过长。
+- 命令输出过大。
+- 需要把过程压缩成给下一个 agent 的上下文。
+- 用户要求总结当前状态。
+
+输出结构：
+
+```text
+目标
+当前状态
+关键决策
+已完成
+未完成
+阻塞
+下一步
+关键文件
+```
+
+第一阶段先做 skill，不做复杂工具。后续可以再参考 `distill` 和 `token-savior` 做自动压缩工具。
+
+## 平台适配
+
+### Claude 适配
+
+第一阶段 Claude 适配目标：
+
+- 能通过项目内 `CLAUDE.md` 识别 vibecoding 规则。
+- 能通过 `.claude-plugin/plugin.json` 或等价安装方式识别插件元信息。
+- 能发现 `skills/` 下的 skill。
+
+建议文件：
+
+```text
+CLAUDE.md
+adapters/claude/plugin.json
+adapters/claude/settings.example.json
+adapters/claude/install.md
+```
+
+`CLAUDE.md` 应包含：
+
+```text
+# Vibecoding Kit
+
+本项目使用 vibecoding workflow。
+
+新会话开始时优先加载 using-vibecoding。
+
+开发任务按以下顺序处理：
+1. planning
+2. implementation
+3. verification
+
+bug 任务按以下顺序处理：
+1. debugging
+2. implementation
+3. verification
+```
+
+### Codex 适配
+
+第一阶段 Codex 适配目标：
+
+- 有插件 manifest。
+- 指向 `skills/`。
+- 指向 hooks 示例。
+- 能说明安装方式。
+
+建议文件：
+
+```text
+adapters/codex/plugin.json
+adapters/codex/hooks.example.json
+adapters/codex/install.md
+```
+
+`plugin.json` 最小字段：
+
+```json
+{
+  "name": "vibe-coding-kit",
+  "version": "0.1.0",
+  "description": "Vibecoding workflow skills for planning, debugging, implementation, review, and verification.",
+  "skills": "../../skills/",
+  "hooks": "./hooks.example.json"
+}
+```
+
+### Cursor 适配
+
+第一阶段 Cursor 适配目标：
+
+- 有插件 manifest。
+- 有 hooks 示例。
+- 明确 Cursor 中 skill / rule / hook 的关系。
+
+建议文件：
+
+```text
+adapters/cursor/plugin.json
+adapters/cursor/hooks.example.json
+adapters/cursor/install.md
+```
+
+`plugin.json` 最小字段：
+
+```json
+{
+  "name": "vibe-coding-kit",
+  "displayName": "Vibecoding Kit",
+  "description": "Workflow skills and hooks for practical vibecoding.",
+  "version": "0.1.0",
+  "skills": "../../skills/",
+  "hooks": "./hooks.example.json"
+}
+```
+
+## Hook 落地
+
+### `session-start`
+
+第一阶段只需要一个简单的 session-start 规则：
+
+目标：提醒 agent 优先识别是否需要 vibecoding workflow。
+
+建议内容：
+
+```text
+Session started.
+
+If the user asks for development work, load using-vibecoding first.
+Choose one of:
+- vibe-planning
+- vibe-debugging
+- vibe-implementation
+- vibe-review
+- vibe-verification
+- vibe-context-compact
+```
+
+不要在第一阶段做复杂自动判断。
+
+### `post-tool-compact`
+
+第一阶段只做预留。
+
+目标：后续接入命令输出压缩工具。
+
+暂不实现自动压缩，避免引入过早复杂度。
+
+## Skill 编写规范
+
+每个 skill 文件使用统一结构：
+
+```text
+---
+name: skill-name
+description: Use when ...
+---
+
+## 目标
+
+## 适用场景
+
+## 输入
+
+## 工作流
+
+## 输出
+
+## 禁止事项
+
+## 示例
+```
+
+### 命名规范
+
+- 全部使用小写。
+- 单词之间用 `-`。
+- 使用动词或 workflow 名称。
+- 不使用宽泛名字，例如 `helper`、`best-practice`、`general`。
+
+推荐：
+
+```text
+vibe-planning
+vibe-debugging
+vibe-verification
+```
+
+不推荐：
+
+```text
+coding-helper
+smart-agent
+general-dev
+```
+
+### 内容规范
+
+skill 应该短、硬、可执行。
+
+每个 skill 都应该有清晰边界：
+
+- 它解决什么问题。
+- 它不解决什么问题。
+- 它和其他 skill 如何衔接。
+
+第一阶段不要写百科式 skill。
+
+## 安装文档落地
+
+第一阶段需要三份安装文档。
+
+### `docs/install-claude.md`
+
+应包含：
+
+- 支持范围。
+- 文件复制方式。
+- `CLAUDE.md` 配置方式。
+- skills 放置路径。
+- 验收 prompt。
+
+### `docs/install-codex.md`
+
+应包含：
+
+- 插件 manifest 位置。
+- skills 路径。
+- hooks 示例。
+- 验收 prompt。
+
+### `docs/install-cursor.md`
+
+应包含：
+
+- 插件 manifest 位置。
+- Cursor rules / skills / hooks 的边界说明。
+- hooks 示例。
+- 验收 prompt。
+
+## 验收标准
+
+第一阶段完成的判断标准不是“文件都创建了”，而是平台能稳定触发正确 workflow。
+
+### 基础验收
+
+必须满足：
+
+1. `skills/using-vibecoding/SKILL.md` 存在。
+2. 至少 5 个 workflow skills 存在。
+3. Claude / Codex / Cursor 三个平台都有 adapter 文档。
+4. 每个平台都有最小 manifest 或配置样例。
+5. 每个平台都有安装说明。
+6. 有统一验收 prompt。
+
+### 行为验收
+
+使用以下 prompt 验收：
+
+```text
+我想给这个项目加一个新功能，先帮我规划一下。
+```
+
+期望行为：
+
+- agent 不直接写代码。
+- agent 进入 planning 流程。
+- 输出目标、范围、模块拆分、实施顺序、验收标准。
+
+使用以下 prompt 验收：
+
+```text
+这个功能不工作，帮我排查。
+```
+
+期望行为：
+
+- agent 不直接乱改。
+- agent 先询问或寻找复现证据。
+- 进入 debugging 流程。
+
+使用以下 prompt 验收：
+
+```text
+实现完成了，帮我确认能不能交付。
+```
+
+期望行为：
+
+- agent 进入 verification 流程。
+- 明确已验证项和未验证项。
+- 给出是否可交付判断。
+
+## 第一阶段实施顺序
+
+推荐按以下顺序落地：
+
+### 第一步：创建骨架目录
+
+创建：
+
+```text
+skills/
+adapters/
+hooks/
+docs/
+examples/
+```
+
+### 第二步：创建 bootstrap skill
+
+创建：
+
+```text
+skills/using-vibecoding/SKILL.md
+```
+
+这是第一阶段最重要的文件。
+
+### 第三步：创建核心 workflow skills
+
+创建：
+
+```text
+skills/vibe-planning/SKILL.md
+skills/vibe-debugging/SKILL.md
+skills/vibe-implementation/SKILL.md
+skills/vibe-review/SKILL.md
+skills/vibe-verification/SKILL.md
+skills/vibe-context-compact/SKILL.md
+```
+
+### 第四步：创建平台 adapters
+
+创建：
+
+```text
+adapters/claude/plugin.json
+adapters/codex/plugin.json
+adapters/cursor/plugin.json
+```
+
+以及对应安装说明。
+
+### 第五步：创建 session-start hook 说明
+
+创建：
+
+```text
+hooks/session-start/README.md
+hooks/session-start/session-start.md
+```
+
+第一阶段不需要复杂脚本。
+
+### 第六步：创建验收文档
+
+创建：
+
+```text
+docs/acceptance-checklist.md
+```
+
+把验收 prompt 和期望行为写进去。
+
+## 第一阶段完成后的状态
+
+完成后，当前项目应该具备以下形态：
+
+```text
+这是一个 vibecoding workflow kit。
+它不是大而全 agent OS。
+它可以安装到 Claude、Codex、Cursor。
+它通过 using-vibecoding 统一入口选择 workflow。
+它通过少量高质量 skills 约束 agent 工作方式。
+它后续可以继续扩展 compact-output、project-map、session-memory 和 MCP 能力。
+```
+
+## 风险控制
+
+### 风险一：过早复制 ECC
+
+避免方式：
+
+- 第一阶段最多保留 6 到 8 个 skill。
+- 不引入大量业务域 skill。
+- 不引入 agents 大库。
+
+### 风险二：过早复制 token-savior
+
+避免方式：
+
+- 第一阶段不做 MCP server。
+- 不做完整 memory database。
+- 只预留 `post-tool-compact`。
+
+### 风险三：skill 写成普通提示词
+
+避免方式：
+
+- 每个 skill 必须有触发条件。
+- 每个 skill 必须有输出结构。
+- 每个 skill 必须有禁止事项。
+- 每个 skill 必须能和其他 skill 衔接。
+
+### 风险四：多平台适配失控
+
+避免方式：
+
+- 第一阶段只做 Claude / Codex / Cursor。
+- Gemini、OpenCode、Kiro、Qwen、Zed 后续再做。
+
+## 下一步建议
+
+第一阶段下一步可以直接开始创建这些文件：
+
+```text
+skills/using-vibecoding/SKILL.md
+skills/vibe-planning/SKILL.md
+skills/vibe-debugging/SKILL.md
+skills/vibe-implementation/SKILL.md
+skills/vibe-review/SKILL.md
+skills/vibe-verification/SKILL.md
+skills/vibe-context-compact/SKILL.md
+adapters/claude/plugin.json
+adapters/codex/plugin.json
+adapters/cursor/plugin.json
+hooks/session-start/session-start.md
+docs/acceptance-checklist.md
+```
+
+优先级最高的是 `skills/using-vibecoding/SKILL.md`。它决定整个项目是否能形成统一入口，而不是变成一堆散乱 skill。