diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index fcf31b0f..ff4b221d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,97 +1,46 @@ -# VibeCoding Kernel v8.9 +# VibeCoding Kernel v9.1.0 -> Talk is cheap. Show me the code. — Linus Torvalds +## 铁律 (违反即失败) -## 身份 +1. **先搜后写**: augment-context-engine 搜现有实现 → 不可用时 grep -r +2. **先规后码**: Path B+ 任务必须先 plan.md → cunzhi [PLAN_CONFIRMED] 后才能写代码 +3. **先测后码**: E 阶段写功能代码前必须先写/更新测试 (RED→GREEN→REFACTOR) +4. **不确定就问**: 歧义/架构决策 → cunzhi 向用户确认, 不猜 +5. **不破坏已有**: 改代码前读测试, 改后跑测试, 红了就修 +6. **compact 前存档**: /compact 前把关键决策写入 .ai_state/knowledge.md +7. **只改需要改的**: 不重构任务范围外的代码, 不加未要求的功能 +8. **避免过度工程**: 用最简方案解决问题, YAGNI 优先 +9. **commit 粒度**: 每个逻辑变更独立 commit, message 用 conventional commits +10. **交付必复盘**: V 阶段完成后必须 diff 分析→提炼 lessons→写入 knowledge.md -你是一个工程化 AI 编程协作系统。你不只是写代码——你按工程流程交付软件。 +## 系统入口 -## 铁律 (5 条, 无例外) +- `/vibe-dev {需求}` — 自动 P.A.C.E. 路由, 开始开发 +- `/vibe-init` — 初始化 .ai_state/, 新项目用 +- `/vibe-resume` — 中断恢复 (读 .ai_state/ 断点) +- `/vibe-status` — 查看当前进度 -1. **先理解再动手** — 任何任务开始前, 用 augment-context-engine 扫描现有代码 -2. **先规划再编码** — Path B+ 必须输出 plan.md, cunzhi 确认后才能写代码 -3. **先测试再交付** — 改了什么就测什么, delivery-gate hook 自动拦截未测试的交付 -4. **每步可追溯** — .ai_state/ 实时更新, kanban TODO→DOING→DONE -5. **人确认再推进** — 关键节点调用 cunzhi MCP 等待用户确认 (降级: 对话确认) +## 子代理 (5 个, sonnet 模型) -## 三层分工 - -| 层 | 负责 | 不做 | -|:---|:---|:---| -| **Superpowers + Plugins** | 方法论 (怎么做 TDD/Debug/Review) | 编排 | -| **MCP 工具** | 执行 (搜索/确认/文档查询) | 决策 | -| **VibeCoding** | 编排 (什么时候/用什么/做多少) | 重复教 AI 已知的事 | - -## 工具注册表 - -### MCP (编排层) - -| MCP | 用途 | 降级 | -|:---|:---|:---| -| augment-context-engine | 语义代码搜索, R/D/E 阶段 | grep + find | -| cunzhi | 人工确认检查点, 全阶段 | 对话问答 (不可跳过确认本身) | -| mcp-deepwiki | 开源库文档查询, R/D 阶段 | web search | - -### Plugins (触发层, 开机预装) - -code-review · commit-commands · feature-dev · frontend-design · hookify · pr-review-toolkit · security-guidance · superpowers@superpowers-marketplace - -> VibeCoding 编排 WHEN/WHERE, Plugins 提供 HOW。用户不需要知道 Superpowers 存在。 - -### 降级通则 - -MCP 不可用 → 用 CLI 替代 (见各 skill 降级字段)。 -Plugin 不可用 → 用 VibeCoding skill 内联逻辑。 -全不可用 → 回退到 AI 内置能力, 保持流程不中断。 +builder (background) / validator / explorer / e2e-runner / security-auditor ## 工作流 -1. **P.A.C.E. 路由** → 读 `workflows/pace.md` 判断复杂度 (A/B/C/D) -2. **RIPER-7 编排** → 读 `workflows/riper-7.md` 按阶段执行 -3. **Skills 按需加载** → 只在对应阶段读取对应 skill +P.A.C.E. 路由 → RIPER-7 阶段 → Skills **自动触发** (非手动调用) +每个 RIPER 阶段绑定必须执行的 skills, 详见 .claude/workflows/ -### 分级加载 (核心优化) +## 质量门 (hooks 自动执行) -| Path | 加载内容 | 约行数 | 约 tokens | -|:---|:---|:---|:---| -| A | CLAUDE.md + rules.md | ~130L | ~250 | -| B | + pace.md + riper-7.md + 相关 skills (6个) | ~540L | ~900 | -| C/D | + agent-teams + security-review + 全量 skills | ~700L | ~1200 | +- PostToolUse: TDD 检查 (写源码前是否有测试) +- Stop: LLM-as-Judge 交付审查 + delivery-gate 机械检查 +- SubagentStop: 子代理产出审查 -## 状态管理 +## 状态持久化 -``` -.ai_state/ ← 当前任务状态 (每次会话) -├── session.md ← 当前阶段/Path/进度 -├── doing.md ← 正在做的 TODO -├── design.md ← brainstorm 输出 -├── plan.md ← plan-first 输出 -├── verified.md ← 验证结果 -├── review.md ← 审查结果 -├── conventions.md ← 项目约定 -└── archive/ ← 历史归档 +.ai_state/ 目录: session → design → plan → doing → verified → review → archive +/memory 管理跨会话记忆 (官方 auto-memory) -.knowledge/ ← 跨会话经验 (持久) -├── patterns.md ← 成功模式 -├── pitfalls.md ← 已知陷阱 -├── decisions.md ← ADR 记录 -└── tools.md ← 工具使用经验 -``` +## MCP (配置于 .mcp.json) -## Agent Teams (Path C+) - -5 个子代理, 全部 Sonnet 4.6, worktree 隔离: -- **builder**: 构建实现 (isolation: worktree) -- **validator**: 测试验证 (isolation: worktree) -- **explorer**: 代码探索 (background: true, 只读) -- **e2e-runner**: E2E 测试 (isolation: worktree) -- **security-auditor**: 安全扫描 (background: true) - -## 新手指引 - -不知道怎么开始?说 "我想做 XXX" 即可。系统自动: -1. 分析任务复杂度 → 选择 Path -2. 展示执行计划预览 -3. 等你确认后开始 - -或运行 `/vibe-init` 初始化项目结构。 +augment-context-engine / cunzhi / mcp-deepwiki +降级: augment→grep | cunzhi→对话确认 | deepwiki→WebSearch diff --git a/.claude/agents/builder.md b/.claude/agents/builder.md index 2896d5d1..b53284e1 100644 --- a/.claude/agents/builder.md +++ b/.claude/agents/builder.md @@ -1,12 +1,34 @@ --- name: builder -model: sonnet-4-6 -isolation: worktree +description: 实现功能代码。限定文件范围内编写, 每个子任务完成后 commit。 +model: sonnet memory: project -skills: [tdd, code-quality, context7] permissionMode: default +background: true +tools: + - Read + - Write + - Edit + - MultiEdit + - Bash + - Glob + - Grep + - Task(validator) --- -构建者。按 plan.md 中分配的任务实现代码。 -遵循 conventions.md 约定, 读 .knowledge/pitfalls.md 规避已知问题。 -完成后更新 doing.md: DOING → DONE。 +你是 Builder — 专注实现, 不做设计决策。 + +## 执行协议 + +1. 只修改任务指定的文件范围, 不越界 +2. 写代码前先写/更新测试 (RED→GREEN) +3. 每个子任务: `git add` 相关文件 → `git commit -m "feat: {描述}"` +4. 遇到设计决策 → 停止, 报告主代理 +5. 完成输出: 修改文件列表 + 测试结果 + 未解决问题 + +## 质量标准 + +- 遵循 .ai_state/conventions.md +- 参考 .ai_state/knowledge.md 避免已知坑 +- 不引入 TODO/FIXME, 不留半成品 +- 完成后调用 validator 验证 diff --git a/.claude/agents/e2e-runner.md b/.claude/agents/e2e-runner.md index 602f8ce2..7a1c76f4 100644 --- a/.claude/agents/e2e-runner.md +++ b/.claude/agents/e2e-runner.md @@ -1,11 +1,19 @@ --- name: e2e-runner -model: sonnet-4-6 -isolation: worktree +description: 端到端测试。使用 Playwright 运行 E2E 测试并报告。 +model: sonnet memory: project -skills: [e2e-testing] -tools: [Read, Write, Bash] +permissionMode: default +tools: + - Read + - Bash + - Glob + - Grep --- -E2E 测试专用。运行 Playwright 或等效 E2E 框架。 -失败时截图保存, 将结果写入 verified.md。 +你是 E2E Runner — 运行端到端测试, 报告结果。 + +## 步骤 +1. 读 .ai_state/plan.md 了解测试范围 +2. npx playwright test (或项目 e2e 命令) +3. 报告: 通过率 + 失败列表 + 截图路径 diff --git a/.claude/agents/explorer.md b/.claude/agents/explorer.md index 18541586..777cc42b 100644 --- a/.claude/agents/explorer.md +++ b/.claude/agents/explorer.md @@ -1,13 +1,20 @@ --- name: explorer -model: sonnet-4-6 -background: true +description: 只读搜索分析。搜索代码库、分析依赖、查找模式。 +model: sonnet memory: project permissionMode: bypassPermissions -tools: [Read] +tools: + - Read + - Glob + - Grep --- -探索者。后台只读运行。 -扫描项目依赖、导入关系、集成点。 -为 builder 和 validator 提供上下文信息。 -不写文件, 不执行命令。 +你是 Explorer — 只读调研, 绝对不修改文件。 + +## 方法 +1. 接收主题 → 搜索关键词 +2. grep -r + glob 广度搜索 +3. 深入相关文件 +4. 参考 .ai_state/knowledge.md +5. 输出: 发现摘要 + 文件引用 + 建议 diff --git a/.claude/agents/security-auditor.md b/.claude/agents/security-auditor.md index 900832ba..757a4dcc 100644 --- a/.claude/agents/security-auditor.md +++ b/.claude/agents/security-auditor.md @@ -1,12 +1,21 @@ --- name: security-auditor -model: sonnet-4-6 -background: true +description: 安全审计。OWASP Top 10、依赖漏洞、密钥泄露检查。 +model: sonnet memory: project -skills: [security-review] -tools: [Read, Bash] +permissionMode: bypassPermissions +tools: + - Read + - Bash + - Glob + - Grep --- -安全扫描。后台运行。 -检查硬编码密钥, SQL 注入, XSS, 依赖漏洞。 -发现问题写入 verified.md 并通知主代理。 +你是 Security Auditor — 审计安全, 不修改代码。 + +## 审计清单 +1. OWASP Top 10 (注入/XSS/CSRF) +2. npm audit / pip audit / cargo audit +3. grep 硬编码密钥 (.env, API key, token) +4. .gitignore 覆盖敏感文件 +5. 输出: CRITICAL/HIGH/MEDIUM/LOW 分级 + 修复建议 diff --git a/.claude/agents/validator.md b/.claude/agents/validator.md index 715c736b..ba276ad3 100644 --- a/.claude/agents/validator.md +++ b/.claude/agents/validator.md @@ -1,12 +1,23 @@ --- name: validator -model: sonnet-4-6 -isolation: worktree +description: 验证代码质量。运行测试、lint、类型检查。 +model: sonnet memory: project -tools: [Read, Bash, mcp__cunzhi__*] -description: 测试验证 — builder 完成后自动触发 +permissionMode: default +tools: + - Read + - Bash + - Glob + - Grep --- -验证者。builder 完成任务后自动触发。 -运行测试, 检查类型, lint。 -通过 → 确认 DONE。不通过 → 退回 builder 并附上失败信息。 +你是 Validator — 只验证, 不修改代码。 + +## 验证清单 +1. 运行项目测试 (自动检测: npm test / pytest / cargo test / go test) +2. lint (eslint / ruff / clippy) +3. 类型检查 (tsc --noEmit / mypy / cargo check) +4. .ai_state/conventions.md 规范检查 +5. 无硬编码密钥 + +## 输出: PASS (全过) 或 FAIL (失败项 + 错误 + 修复建议) diff --git a/.claude/commands/vibe-brainstorm.md b/.claude/commands/vibe-brainstorm.md deleted file mode 100644 index 2cec121b..00000000 --- a/.claude/commands/vibe-brainstorm.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: vibe-brainstorm -description: 显式触发头脑风暴 — 不进入完整开发流程 -allowed-tools: Read, Write, mcp__augment-context-engine__*, mcp__mcp-deepwiki__*, mcp__cunzhi__* ---- - -# /vibe-brainstorm — 头脑风暴 - -只做 RIPER R₀b 阶段, 不进入后续开发。 -适合: 还没想好怎么做, 先探讨方案。 - -1. 加载 skills/brainstorm -2. 执行头脑风暴流程 -3. 输出 .ai_state/design.md -4. 结束 (不自动进入 R/D/P/E) - -用户可以之后用 `/vibe-dev` 基于 design.md 继续。 diff --git a/.claude/commands/vibe-dev.md b/.claude/commands/vibe-dev.md index 489966dd..995f2afc 100644 --- a/.claude/commands/vibe-dev.md +++ b/.claude/commands/vibe-dev.md @@ -1,18 +1,14 @@ --- name: vibe-dev -description: 智能开发入口 — 自动路由到完整工程流程 -allowed-tools: Read, Write, Bash, mcp__cunzhi__*, mcp__augment-context-engine__*, mcp__mcp-deepwiki__* +description: 开始开发 — 自动 P.A.C.E. 路由, 进入 RIPER 流程 --- +接收需求: $ARGUMENTS -# /vibe-dev — 智能开发入口 +## 执行步骤 +1. 读 .claude/workflows/pace.md → 评估复杂度 → 选择 Path A/B/C/D +2. 读 .claude/workflows/riper-7.md → 按路径执行对应阶段 +3. 路径 A: 直接开发 (R→E→T→V) +4. 路径 B+: 先规划后执行 (R₀b→R→D→P→E→T→V) +5. 每个检查点使用 cunzhi 确认 -用户说 `/vibe-dev "做个搜索功能"` 后: - -1. 检查 .ai_state/ 是否存在, 不存在则先跑 quickstart -2. augment-context-engine 快速扫描项目 -3. P.A.C.E. 路由 (workflows/pace.md) → 判定 Path -4. 向用户展示任务分析和执行计划预览 -5. cunzhi 确认 Path 选择 -6. 进入 RIPER-7 (workflows/riper-7.md) 按阶段执行 - -这是最常用的入口。新手直接用这个就行。 +如果 .ai_state/ 不存在, 先执行 /vibe-init。 diff --git a/.claude/commands/vibe-init.md b/.claude/commands/vibe-init.md index b9f4c42b..d9a2f640 100644 --- a/.claude/commands/vibe-init.md +++ b/.claude/commands/vibe-init.md @@ -1,21 +1,14 @@ --- name: vibe-init -description: 初始化 VibeCoding 项目结构 -allowed-tools: Read, Write, Bash +description: 初始化项目 .ai_state 状态目录 --- -# /vibe-init — 项目初始化 +## 执行步骤 -1. 检查项目根目录是否已有 .ai_state/ -2. 如果没有: - ```bash - mkdir -p .ai_state/archive - mkdir -p .knowledge - ``` -3. 从 `.claude/templates/ai-state/` 复制模板到 `.ai_state/` -4. 从 `.claude/templates/knowledge/` 复制模板到 `.knowledge/` -5. 检测项目类型 (package.json/requirements.txt/go.mod) -6. 初始化 conventions.md 中的项目信息 -7. 触发 quickstart 引导 +1. 创建 .ai_state/ 目录 +2. 从 .claude/templates/ai-state/ 复制模板文件 +3. 读项目 README/package.json 填充 conventions.md 基础信息 +4. 添加 .ai_state/ 到 .gitignore +5. 输出: 初始化完成, 使用 /vibe-dev {需求} 开始 -如果 .ai_state/ 已存在, 检查完整性并补全缺失文件。 +模板位置: .claude/templates/ai-state/ diff --git a/.claude/commands/vibe-resume.md b/.claude/commands/vibe-resume.md index 56729ba9..c8db1a7f 100644 --- a/.claude/commands/vibe-resume.md +++ b/.claude/commands/vibe-resume.md @@ -1,23 +1,11 @@ --- name: vibe-resume -description: 中断恢复 — 从上次中断的地方继续 -allowed-tools: Read, Write, Bash, mcp__cunzhi__*, mcp__augment-context-engine__* +description: 从中断处恢复开发 --- +## 执行步骤 +1. 读 .ai_state/session.md → 恢复上下文 +2. 检测断点阶段 (context-loader.cjs 已处理) +3. 告知用户当前状态和下一步 +4. 继续执行 -# /vibe-resume — 中断恢复 - -1. 读 .ai_state/session.md → 获取中断时的 Path + 阶段 -2. 读 .ai_state/doing.md → 获取未完成的 TODO -3. augment-context-engine 快速扫描最近变更 -4. 向用户展示恢复摘要: - ``` - 🔄 恢复上次任务 - ├─ Path: B - ├─ 中断阶段: E (执行) - ├─ 已完成: T-001, T-002 - ├─ 待继续: T-003, T-004 - └─ 最后变更: src/auth/login.ts - ``` -5. cunzhi 确认后继续 - -等效于 `/resume` 官方命令 + VibeCoding 上下文恢复。 +等效于: 读取 SessionStart hook 输出 + 提示恢复 diff --git a/.claude/commands/vibe-status.md b/.claude/commands/vibe-status.md index ff8e840b..d4890e93 100644 --- a/.claude/commands/vibe-status.md +++ b/.claude/commands/vibe-status.md @@ -1,22 +1,9 @@ --- name: vibe-status -description: 查看当前任务状态和进度 -allowed-tools: Read, Bash +description: 查看当前开发进度 --- - -# /vibe-status — 状态查看 - -1. 读 .ai_state/session.md → 当前 Path + 阶段 -2. 读 .ai_state/doing.md → TODO/DOING/DONE 统计 -3. 如果有活跃 Agent Teams: `claude agents` 列出活跃子代理 -4. 输出看板: - ``` - 📊 VibeCoding 状态 - ├─ 版本: v8.9 - ├─ Path: B | 阶段: E (执行) - ├─ 进度: ████████░░ 4/5 (80%) - ├─ TODO: T-005 (实现搜索过滤) - ├─ DOING: — - ├─ DONE: T-001, T-002, T-003, T-004 - └─ Agents: builder (active), validator (idle) - ``` +## 执行步骤 +1. 读 .ai_state/session.md → 当前阶段 +2. 读 .ai_state/doing.md → 进行中任务 +3. 读 .ai_state/plan.md → 完成/未完成计数 +4. 输出看板格式: TODO / DOING / DONE diff --git a/.claude/hooks/context-loader.cjs b/.claude/hooks/context-loader.cjs index dc2315ec..fe4ede30 100644 --- a/.claude/hooks/context-loader.cjs +++ b/.claude/hooks/context-loader.cjs @@ -1,71 +1,72 @@ -// VibeCoding v8.9 — SessionStart Hook -// 加载项目上下文 + 智能断点恢复 -const fs = require('node:fs'); -const path = require('node:path'); +#!/usr/bin/env node +"use strict"; +// VibeCoding v9.1.0 — SessionStart Hook (Context Loader) +// 恢复断点 + 按需加载上下文 +var fs = require("fs"); +var path = require("path"); -function readHead(file, lines) { +process.on("uncaughtException", function() { process.exit(0); }); +if (process.env.VIBECODING_HOOKS_DISABLED === "1") process.exit(0); + +function exists(f) { try { return fs.existsSync(f); } catch { return false; } } +function readHead(f, n) { try { - const content = fs.readFileSync(file, 'utf8'); - return content.split('\n').slice(0, lines).join('\n'); - } catch { - return ''; + var lines = fs.readFileSync(f, "utf8").split("\n"); + return lines.slice(0, n).join("\n"); + } catch { return ""; } +} + +var ctx = []; + +// 1. conventions (始终加载) +if (exists(".ai_state/conventions.md")) { + ctx.push("📋 conventions:\n" + readHead(".ai_state/conventions.md", 30)); +} + +// 2. knowledge (跨会话经验, 配合 /memory auto-memory) +if (exists(".ai_state/knowledge.md")) { + var kn = readHead(".ai_state/knowledge.md", 20); + if (kn.trim()) ctx.push("📚 knowledge:\n" + kn); +} + +// 3. lessons (错误教训) +if (exists(".ai_state/lessons.md")) { + var ls = readHead(".ai_state/lessons.md", 15); + if (ls.trim()) ctx.push("⚠️ lessons:\n" + ls); +} + +// 4. 断点恢复: 检测中断阶段 +if (exists(".ai_state/session.md")) { + var session = fs.readFileSync(".ai_state/session.md", "utf8"); + ctx.push("🔄 session:\n" + session); + + // 推断当前阶段 + if (exists(".ai_state/review.md")) { + ctx.push("⚠️ 断点: V(验收)阶段, 上次在最终审查中中断"); + } else if (exists(".ai_state/verified.md")) { + ctx.push("⚠️ 断点: T(测试)阶段, 验证已开始"); + } else if (exists(".ai_state/doing.md")) { + ctx.push("📝 doing:\n" + readHead(".ai_state/doing.md", 20)); + ctx.push("⚠️ 断点: E(执行)阶段, 开发进行中"); + } else if (exists(".ai_state/plan.md")) { + ctx.push("📐 plan:\n" + readHead(".ai_state/plan.md", 25)); + ctx.push("⚠️ 断点: P(计划)阶段已完成, 继续执行"); + } else if (exists(".ai_state/design.md")) { + ctx.push("🎨 design:\n" + readHead(".ai_state/design.md", 15)); + ctx.push("⚠️ 断点: D(设计)阶段已完成"); + } +} else { + // 无 session = 新会话, 检查是否有 .ai_state 目录 + if (!exists(".ai_state")) { + ctx.push("💡 新项目: 使用 /vibe-init 初始化, 或 /vibe-dev {需求} 直接开始"); } } -function exists(f) { - try { - return fs.existsSync(f); - } catch { - return false; - } -} - -const ctx = []; - -// 1. 加载 conventions (始终) -if (exists('.ai_state/conventions.md')) { - ctx.push(`📋 conventions:\n${readHead('.ai_state/conventions.md', 30)}`); -} - -// 2. 加载 .knowledge/ (跨会话经验) -for (const f of ['patterns.md', 'pitfalls.md', 'decisions.md', 'tools.md']) { - const p = path.join('.knowledge', f); - if (exists(p)) { - const head = readHead(p, 15); - if (head.trim()) ctx.push(`📚 ${f}:\n${head}`); - } -} - -// 3. 断点恢复: 检测中断阶段 -if (exists('.ai_state/session.md')) { - const session = fs.readFileSync('.ai_state/session.md', 'utf8'); - ctx.push(`🔄 session:\n${session}`); - - // 检测高级阶段断点 - if (exists('.ai_state/review.md')) { - ctx.push('⚠️ 断点: 已到 V(验收) 阶段, 上次可能在最终审查中中断'); - } else if (exists('.ai_state/verified.md')) { - ctx.push('⚠️ 断点: 已到 T(测试) 阶段, 验证已开始'); - } else if (exists('.ai_state/doing.md')) { - const doing = readHead('.ai_state/doing.md', 20); - ctx.push(`📝 doing:\n${doing}`); - } -} - -// 4. plan.md 和 design.md (如果存在) -if (exists('.ai_state/plan.md')) { - ctx.push(`📐 plan:\n${readHead('.ai_state/plan.md', 25)}`); -} -if (exists('.ai_state/design.md')) { - ctx.push(`🎨 design:\n${readHead('.ai_state/design.md', 15)}`); - // 异常场景: design.md 存在但 session.md 不存在 (异常中断) - if (!exists('.ai_state/session.md')) { - ctx.push( - '⚠️ design.md 存在但 session.md 缺失, 可能是上次任务异常中断。建议 /vibe-resume 恢复或 /vibe-dev 重新开始。' - ); - } +// 5. design + plan (如果存在且未在断点中加载) +if (exists(".ai_state/plan.md") && !exists(".ai_state/doing.md")) { + // plan 存在但 doing 不存在 → 可能刚完成规划 } if (ctx.length > 0) { - process.stdout.write(ctx.join('\n---\n')); + process.stdout.write(ctx.join("\n---\n")); } diff --git a/.claude/hooks/delivery-gate.cjs b/.claude/hooks/delivery-gate.cjs index 6aaed0b8..41b83619 100644 --- a/.claude/hooks/delivery-gate.cjs +++ b/.claude/hooks/delivery-gate.cjs @@ -1,91 +1,83 @@ -// VibeCoding v8.9 — Stop Hook (Delivery Gate) +#!/usr/bin/env node +"use strict"; +// VibeCoding v9.1.0 — Stop Hook (Delivery Gate) // 阻止未完成任务/未测试代码的交付 -const fs = require('node:fs'); -const { execSync } = require('node:child_process'); +var fs = require("fs"); +var child_process = require("child_process"); -function exists(f) { - try { - return fs.existsSync(f); - } catch { - return false; - } -} +process.on("uncaughtException", function() { process.exit(0); }); +if (process.env.VIBECODING_HOOKS_DISABLED === "1") process.exit(0); + +function exists(f) { try { return fs.existsSync(f); } catch { return false; } } function runQuiet(cmd, timeout) { try { - execSync(cmd, { timeout: timeout || 60000, stdio: 'pipe' }); + child_process.execSync(cmd, { timeout: timeout || 60000, stdio: "pipe" }); return true; - } catch { - return false; - } + } catch { return false; } } function hasScript(name) { try { - const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8')); - return Boolean(pkg.scripts && pkg.scripts[name]); - } catch { - return false; - } + var pkg = JSON.parse(fs.readFileSync("package.json", "utf8")); + return !!(pkg.scripts && pkg.scripts[name]); + } catch { return false; } } -// 获取当前 Path -let currentPath = 'A'; -try { - const session = fs.readFileSync('.ai_state/session.md', 'utf8'); - const m = session.match(/path:\s*([ABCD])/i); - if (m) currentPath = m[1].toUpperCase(); -} catch {} - -const errors = []; - -// === 检查 1: plan.md 完成度 (Path B+) === -if (currentPath !== 'A' && exists('.ai_state/plan.md')) { +var d = ""; +process.stdin.on("data", function(c) { d += c; }); +process.stdin.on("end", function() { try { - const plan = fs.readFileSync('.ai_state/plan.md', 'utf8'); - const total = (plan.match(/- \[[ x]\]/g) || []).length; - const done = (plan.match(/- \[x\]/gi) || []).length; - if (total > 0 && done < total) { - errors.push(`plan.md: ${done}/${total} 完成, ${total - done} 个任务未完成`); + var input = JSON.parse(d); + + // 检查 last_assistant_message (v2.1.47+ 新增) + var lastMsg = input.last_assistant_message || ""; + + // 1. 检查 plan.md 未完成任务 + if (exists(".ai_state/plan.md")) { + var plan = fs.readFileSync(".ai_state/plan.md", "utf8"); + var unchecked = (plan.match(/^- \[ \]/gm) || []).length; + if (unchecked > 0) { + process.stderr.write("[DeliveryGate] BLOCKED: " + unchecked + " unchecked tasks in plan.md\n"); + process.exit(2); + } } - } catch {} -} -// === 检查 2: npm test (Path B+) === -if (currentPath !== 'A' && hasScript('test')) { - if (!runQuiet('npm test', 90000)) { - errors.push('npm test 失败'); - } -} + // 2. Path B+: 运行测试 (仅当有测试脚本时) + var isStrictPath = exists(".ai_state/design.md") || exists(".ai_state/plan.md"); + if (isStrictPath) { + // 多语言测试检测 + var testCmd = null; + if (hasScript("test")) testCmd = "npm test"; + else if (exists("pytest.ini") || exists("pyproject.toml")) testCmd = "pytest --tb=short -q"; + else if (exists("Cargo.toml")) testCmd = "cargo test"; + else if (exists("go.mod")) testCmd = "go test ./..."; -// === 检查 3: ESLint (Path C+) === -const isStrictPath = currentPath === 'C' || currentPath === 'D'; -const hasEslintConfig = - exists('.eslintrc') || - exists('.eslintrc.js') || - exists('.eslintrc.json') || - exists('.eslintrc.cjs') || - exists('eslint.config.js') || - exists('eslint.config.mjs') || - exists('eslint.config.cjs'); -if (isStrictPath && hasEslintConfig) { - if (!runQuiet('npx eslint . --max-warnings 0', 60000)) { - errors.push('ESLint 检查未通过'); - } -} + if (testCmd) { + var passed = runQuiet(testCmd, 120000); + if (!passed) { + process.stderr.write("[DeliveryGate] BLOCKED: tests failed (" + testCmd + ")\n"); + process.exit(2); + } + } -// === 检查 4: TypeScript (Path B+) === -if (currentPath !== 'A' && exists('tsconfig.json')) { - if (!runQuiet('npx tsc --noEmit', 60000)) { - errors.push('TypeScript 类型检查失败'); - } -} + // ESLint (仅当有配置时) + var hasEslint = exists(".eslintrc.js") || exists(".eslintrc.json") || exists(".eslintrc.yml") || exists("eslint.config.js") || exists("eslint.config.mjs"); + if (hasEslint) { + runQuiet("npx eslint . --max-warnings=0 2>/dev/null", 30000); + // ESLint 失败不阻塞, 只警告 + } + } -// === 输出 === -if (errors.length > 0) { - process.stderr.write(`🚫 Delivery Gate 拦截:\n${errors.map(e => ` ❌ ${e}`).join('\n')}`); - process.exit(2); // exit 2 = block -} else { - process.stdout.write(`✅ Delivery Gate 通过 (Path ${currentPath})`); - process.exit(0); -} + // 3. 检查 doing.md 是否有未完成项 + if (exists(".ai_state/doing.md")) { + var doing = fs.readFileSync(".ai_state/doing.md", "utf8"); + var inProgress = (doing.match(/🔄|IN_PROGRESS|进行中/g) || []).length; + if (inProgress > 0) { + process.stderr.write("[DeliveryGate] WARNING: " + inProgress + " tasks still in progress\n"); + } + } + + } catch(e) {} + console.log(d); +}); diff --git a/.claude/hooks/post-edit.cjs b/.claude/hooks/post-edit.cjs new file mode 100644 index 00000000..fc6f9327 --- /dev/null +++ b/.claude/hooks/post-edit.cjs @@ -0,0 +1,27 @@ +#!/usr/bin/env node +"use strict"; +// VibeCoding v9.1.0 — PostToolUse Hook (Post-Edit) +// 非阻塞: 格式化提醒 (Block-at-Commit 策略) +var d = ""; +process.on("uncaughtException", function() { process.exit(0); }); +process.stdin.on("data", function(c) { d += c; }); +process.stdin.on("end", function() { + try { + var input = JSON.parse(d); + var p = input.tool_input && input.tool_input.file_path || ""; + + // 阻止在系统目录外创建不必要的 .md 文件 + if (/\.(md|txt)$/.test(p) + && !/(README|CLAUDE|AGENTS|CONTRIBUTING|CHANGELOG|LICENSE|API|ARCHITECTURE|SECURITY|MIGRATION)\.md$/.test(p) + && !/\.claude\//.test(p) + && !/\.ai_state\//.test(p) + && !/docs?\//.test(p) + && !/src\//.test(p) + && !/plans?\//.test(p)) { + console.error("[Hook] BLOCKED: 不必要的文档文件: " + p); + console.error("[Hook] 使用 README.md, docs/, 或 .ai_state/"); + process.exit(2); + } + } catch {} + console.log(d); +}); diff --git a/.claude/hooks/pre-bash.cjs b/.claude/hooks/pre-bash.cjs new file mode 100644 index 00000000..87f28ece --- /dev/null +++ b/.claude/hooks/pre-bash.cjs @@ -0,0 +1,45 @@ +#!/usr/bin/env node +"use strict"; +// VibeCoding v9.1.0 — PreToolUse Hook (Bash Safety Guard) +// 拦截危险命令, 使用 hookSpecificOutput.permissionDecision +var d = ""; +process.on("uncaughtException", function() { process.exit(0); }); +process.stdin.on("data", function(c) { d += c; }); +process.stdin.on("end", function() { + try { + var input = JSON.parse(d); + var cmd = (input.tool_input && input.tool_input.command) || ""; + + // DENY: rm -rf / 或 根目录危险操作 + if (/\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|--recursive)/.test(cmd) && /\s\/(\s|$)/.test(cmd)) { + process.stderr.write("[SECURITY] Blocked: rm -rf /\n"); + process.exit(2); + } + + // DENY: sudo + if (/\bsudo\b/.test(cmd)) { + process.stderr.write("[SECURITY] Blocked: sudo\n"); + process.exit(2); + } + + // DENY: eval (精确匹配, 排除 node eval.js 类误报) + if (/(^|[;&|])\s*eval\b/.test(cmd)) { + process.stderr.write("[SECURITY] Blocked: eval\n"); + process.exit(2); + } + + // DENY: curl pipe bash + if (/\bcurl\b.*\|\s*(ba)?sh/.test(cmd) || /\bwget\b.*\|\s*(ba)?sh/.test(cmd)) { + process.stderr.write("[SECURITY] Blocked: curl|bash\n"); + process.exit(2); + } + + // WARN: 敏感文件访问 (不阻塞) + if (/\.(env|pem|key|cert|p12|pfx|jks)\b/.test(cmd) + && !/\.gitignore/.test(cmd) && !/grep/.test(cmd)) { + process.stderr.write("[SECURITY] WARNING: sensitive file access — " + cmd.slice(0, 80) + "\n"); + } + + } catch {} + console.log(d); +}); diff --git a/.claude/hooks/worktree-init.cjs b/.claude/hooks/worktree-init.cjs deleted file mode 100644 index 05a8e6c2..00000000 --- a/.claude/hooks/worktree-init.cjs +++ /dev/null @@ -1,19 +0,0 @@ -// VibeCoding v8.9 — WorktreeCreate Hook -// 在 agent worktree 中初始化 .ai_state -const fs = require('node:fs'); - -function ensureDir(d) { - try { - fs.mkdirSync(d, { recursive: true }); - } catch {} -} - -// 在 worktree 中创建最小 .ai_state -ensureDir('.ai_state'); - -// 只创建 doing.md (子代理需要记录进度) -if (!fs.existsSync('.ai_state/doing.md')) { - fs.writeFileSync('.ai_state/doing.md', '# Worktree Task Progress\n\n'); -} - -process.stdout.write('✅ Worktree .ai_state 已初始化'); diff --git a/.claude/rules/rules.md b/.claude/rules/rules.md index 8f0619dd..d6ab980e 100644 --- a/.claude/rules/rules.md +++ b/.claude/rules/rules.md @@ -1,23 +1,26 @@ -# VibeCoding 项目硬规则 +# 编码规范 (rules.md) -## 代码规则 (从 skills 提取的强制规则) +## 通用 -1. 修 bug 必须写回归测试 (Path B+) -2. 新增 API 必须有入参验证 -3. 数据库查询必须参数化, 禁止字符串拼接 SQL -4. 不提交 console.log/print 调试语句到生产代码 -5. 环境变量不硬编码, 用 .env + process.env +- 函数: 单一职责, <50 行, 清晰命名 +- 错误处理: 不吞异常, 有意义的错误消息 +- 注释: 解释 WHY 不解释 WHAT +- 不使用 any/as any (TS), 不使用 # type: ignore (Python) -## 工作流规则 +## Git -6. 不在 E 阶段修改 design.md (设计已锁定) -7. plan.md 中未完成的任务不能标记为 DONE -8. .knowledge/ 文件不可删除, 只追加 -9. conventions.md 变更需 cunzhi 确认 -10. 每次 commit 必须关联 plan.md 任务编号 (Path B+) +- 分支: feature/{描述}, fix/{描述}, refactor/{描述} +- Commit: conventional commits (feat/fix/refactor/docs/test/chore) +- 每个逻辑变更独立 commit, 不混杂 -## Git 规则 +## 测试 -11. commit message 格式: `type(scope): description [T-XXX]` -12. Path B: squash merge 到主分支 -13. Path C+: 按功能分 commit, 保留历史 +- 新功能必须有测试 +- 修 bug 先写回归测试 +- 覆盖率: 关键路径 100%, 整体 >80% + +## 安全 + +- 不硬编码密钥/凭据 +- 使用环境变量或 secret manager +- 所有用户输入必须验证/转义 diff --git a/.claude/scripts/vibe-lint.cjs b/.claude/scripts/vibe-lint.cjs deleted file mode 100644 index 62af84ee..00000000 --- a/.claude/scripts/vibe-lint.cjs +++ /dev/null @@ -1,77 +0,0 @@ -// VibeCoding v8.9 — 配置健康检查 -// 运行: node .claude/scripts/vibe-lint.cjs -const fs = require('node:fs'); -const path = require('node:path'); - -let fail = 0; -let ok = 0; -let warn = 0; - -function check(condition, msg) { - if (condition) { - console.log(` ✅ ${msg}`); - ok++; - } else { - console.log(` ❌ ${msg}`); - fail++; - } -} - -function soft(condition, msg) { - if (condition) { - console.log(` ✅ ${msg}`); - ok++; - } else { - console.log(` ⚠️ ${msg}`); - warn++; - } -} - -function exists(f) { - return fs.existsSync(f); -} - -console.log('🔍 VibeCoding v8.9 配置检查\n'); - -console.log('=== 核心文件 ==='); -check(exists('.claude/CLAUDE.md'), 'CLAUDE.md 入口'); -check(exists('.claude/settings.json'), 'settings.json 配置'); -check(exists('.claude/workflows/pace.md'), 'P.A.C.E. 路由'); -check(exists('.claude/workflows/riper-7.md'), 'RIPER-7 编排'); -check(exists('.claude/rules/rules.md'), '项目规则'); - -console.log('\n=== Skills ==='); -const skills = [ - 'brainstorm', - 'cunzhi', - 'tdd', - 'verification', - 'code-quality', - 'knowledge', - 'agent-teams', - 'context7', - 'plan-first', - 'smart-archive', - 'e2e-testing', - 'security-review', - 'quickstart' -]; -skills.forEach(s => check(exists(`.claude/skills/${s}/SKILL.md`), `skill: ${s}`)); - -console.log('\n=== Agents ==='); -['builder', 'validator', 'explorer', 'e2e-runner', 'security-auditor'].forEach(a => - check(exists(`.claude/agents/${a}.md`), `agent: ${a}`) -); - -console.log('\n=== Hooks ==='); -check(exists('.claude/hooks/context-loader.cjs'), 'SessionStart hook'); -check(exists('.claude/hooks/delivery-gate.cjs'), 'Stop hook'); -check(exists('.claude/hooks/worktree-init.cjs'), 'WorktreeCreate hook'); - -console.log('\n=== 项目状态 ==='); -soft(exists('.ai_state'), '.ai_state/ 目录'); -soft(exists('.knowledge'), '.knowledge/ 目录'); -soft(exists('.ai_state/conventions.md'), 'conventions.md'); - -console.log(`\n📊 结果: ${ok} 通过, ${warn} 警告, ${fail} 失败`); -if (fail > 0) process.exit(1); diff --git a/.claude/settings.json b/.claude/settings.json index 8342e0cf..539847fa 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,112 +1,58 @@ { "permissions": { "allow": [ - "Bash(git *)", - "Bash(npm *)", - "Bash(npx *)", + "Read", + "Write", + "Edit", + "MultiEdit", + "Task", + "WebSearch", + "WebFetch", "Bash(node *)", - "Bash(pnpm *)", - "Bash(yarn *)", - "Bash(bun *)", + "Bash(npm test)", + "Bash(npm run *)", + "Bash(npm install *)", + "Bash(npx tsc *)", + "Bash(npx eslint *)", + "Bash(npx prettier *)", + "Bash(npx playwright *)", + "Bash(npx vitest *)", + "Bash(npx jest *)", + "Bash(git add *)", + "Bash(git commit *)", + "Bash(git status)", + "Bash(git diff *)", + "Bash(git log *)", + "Bash(git branch *)", + "Bash(grep *)", + "Bash(find *)", "Bash(cat *)", "Bash(ls *)", - "Bash(find *)", - "Bash(grep *)", "Bash(mkdir *)", "Bash(cp *)", "Bash(mv *)", - "Bash(rm *)", - "Bash(touch *)", - "Bash(echo *)", - "Bash(head *)", - "Bash(tail *)", - "Bash(wc *)", - "Bash(sed *)", - "Bash(awk *)", - "Bash(sort *)", - "Bash(diff *)", - "Bash(curl *)", - "Bash(which *)", - "Bash(pwd)", - "Bash(tsc *)", - "Bash(eslint *)", - "Bash(prettier *)", - "Bash(jest *)", - "Bash(vitest *)", - "Bash(playwright *)", - "Read(*)", - "Write(*)", - "Edit(*)", - "mcp__cunzhi__*", - "mcp__augment-context-engine__*", - "mcp__mcp-deepwiki__*" + "Bash(python *)", + "Bash(pip install *)", + "Bash(cargo *)", + "Bash(go *)", + "Bash(make *)" ], - "deny": ["Bash(rm -rf /)", "Bash(rm -rf ~)", "Bash(chmod 777 *)"] - }, - "plugins": { - "enabled": [ - "code-review", - "commit-commands", - "feature-dev", - "frontend-design", - "hookify", - "plugin-dev", - "pr-review-toolkit", - "security-guidance", - "superpowers@superpowers-marketplace" - ], - "marketplaces": [ - { - "name": "claude-official", - "url": "registry:claude-plugins-official" - }, - { - "name": "claude-community", - "url": "registry:claude-plugins-community" - }, - { - "name": "claude-local", - "url": "local:.claude/plugins" - }, - { - "name": "superpowers-marketplace", - "url": "github:obra/superpowers-marketplace" - } + "deny": [ + "Bash(rm -rf /)", + "Bash(sudo *)", + "Read(./.env)", + "Read(./.env.*)", + "Read(./secrets/**)" ] }, "hooks": { "SessionStart": [ { - "matcher": "", "hooks": [ { "type": "command", "command": "node .claude/hooks/context-loader.cjs", - "timeout": 10000 - } - ] - } - ], - "PreToolUse": [ - { - "matcher": "Write", - "hooks": [ - { - "type": "command", - "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.md$/i.test(p)&&!/^(README|CHANGELOG|LICENSE|API|ARCHITECTURE|SECURITY|MIGRATION|CONTRIBUTING)/i.test(require('path').basename(p))&&!/(docs|src|plans|scripts|templates|.claude|.codex|.ai_state|.knowledge)[\\\\/]/.test(p)){process.stderr.write('Block: AI 不应随意创建 .md 文件: '+p);process.exit(2)}process.exit(0)}catch{process.exit(0)}})\"", - "timeout": 5000 - } - ] - } - ], - "PostToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "command", - "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.(ts|tsx)$/.test(p)){const{execSync}=require('child_process');try{execSync('npx tsc --noEmit 2>&1',{timeout:30000,stdio:'pipe'})}catch(e){process.stdout.write('⚠️ TypeScript 类型错误:\\n'+e.stdout?.toString().slice(0,500))}}process.exit(0)}catch{process.exit(0)}})\"", - "timeout": 35000 + "timeout": 15 } ] } @@ -117,33 +63,73 @@ { "type": "command", "command": "node .claude/hooks/delivery-gate.cjs", - "timeout": 120000 + "timeout": 60 + } + ] + }, + { + "hooks": [ + { + "type": "prompt", + "prompt": "你是交付质量审查员。检查 assistant 的最终回复:\n1. 所有 plan.md 任务已完成? (无未勾选 checkbox)\n2. 代码变更有对应测试? (新功能/修复必须有测试)\n3. 无 TODO/FIXME/HACK 残留?\n4. commit message 符合 conventional commits?\n5. 无硬编码密钥/凭据?\n全部通过→回复 {\"ok\": true}\n任一不通过→回复 {\"ok\": false, \"reason\": \"具体问题\"}", + "timeout": 30 } ] } ], - "WorktreeCreate": [ + "PostToolUse": [ { + "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", - "command": "node .claude/hooks/worktree-init.cjs", - "timeout": 10000 + "command": "node .claude/hooks/post-edit.cjs", + "timeout": 5 + } + ] + }, + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "prompt", + "prompt": "TDD 检查: 刚写入/修改的文件是源代码(非测试)吗?\n如果是源代码且当前 RIPER 阶段是 E(执行):\n- 检查是否有对应的测试文件已存在或刚创建\n- 如果写了功能代码但没有先写测试 → 提醒 RED-GREEN-REFACTOR\n回复 {\"ok\": true} 或 {\"ok\": false, \"reason\": \"先写测试再写实现\"}", + "timeout": 10 + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "node .claude/hooks/pre-bash.cjs", + "timeout": 5 + } + ] + } + ], + "SubagentStop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "子代理完成。检查 last_assistant_message:\n1) 所有子任务完成? 2) 无未解决错误? 3) 符合 conventions.md?\n通过→accept, 有问题→continue。\n回复 JSON {\"ok\": true} 或 {\"ok\": false, \"reason\": \"...\"}", + "timeout": 30 } ] } ] }, "env": { + "VIBECODING_VERSION": "9.1.0", "LANGUAGE": "zh-Hans", "LC_ALL": "zh-Hans", - "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1", - "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1, + "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "API_TIMEOUT_MS": "3000000", "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6", - "ANTHROPIC_API_KEY": "", - "ANTHROPIC_BASE_URL": "", - "VIBECODING_VERSION": "8.9", "VIBECODING_HOOKS_DISABLED": "0" } } diff --git a/.claude/skills/agent-teams/SKILL.md b/.claude/skills/agent-teams/SKILL.md index 7dafbb65..e7d8f5db 100644 --- a/.claude/skills/agent-teams/SKILL.md +++ b/.claude/skills/agent-teams/SKILL.md @@ -1,35 +1,28 @@ --- name: agent-teams -description: 并行分工 + worktree 隔离 — Path C+ +description: 多代理并行协作 — Path C/D 的 E 阶段 context: main --- +## 触发: Path C/D 的 E(执行) 阶段 -## 触发 -P.A.C.E. 路由为 Path C/D 时激活。 +## 前提 +- .claude/agents/ 目录下定义了 builder/validator/explorer 等子代理 +- plan.md 中任务已标注可并行/有依赖 -## 子代理 +## 编排策略 +1. 读 plan.md → 识别无依赖的任务组 +2. 为每组分配 builder 子代理 (background: true) +3. 每个 builder 使用 isolation: worktree 隔离 +4. validator 定期检查各 builder 产出 +5. explorer 负责跨模块调研 -| Agent | 文件 | 模型 | 隔离 | 角色 | -|:---|:---|:---|:---|:---| -| builder | agents/builder.md | sonnet-4-6 | worktree | 实现代码 | -| validator | agents/validator.md | sonnet-4-6 | worktree | 运行测试 | -| explorer | agents/explorer.md | sonnet-4-6 | background | 探索依赖 (只读) | -| e2e-runner | agents/e2e-runner.md | sonnet-4-6 | worktree | E2E 测试 | -| security-auditor | agents/security-auditor.md | sonnet-4-6 | background | 安全扫描 | +## 并行规则 +- 无依赖任务: 并行执行 +- 有依赖任务: 串行, 前置完成后触发 +- 冲突检测: 同文件不并行修改 -## Hooks 集成 - -- **TeammateIdle**: teammate 空闲时自动分配下一个 plan.md 任务 -- **TaskCompleted**: teammate 完成后自动触发 validator 跑测试 -- **WorktreeCreate**: worktree-init.cjs 初始化 .ai_state/ - -## 并行工作协议 - -1. 从 plan.md 读取任务列表, 标注依赖关系 -2. 无依赖任务可并行分配给不同 builder -3. builder 完成 → TaskCompleted hook → validator 自动验证 -4. validator 不通过 → 退回 builder 修复 -5. 全部任务完成 → explorer 扫描集成点 → 主代理合并 - -## 降级 -Agent Teams 不可用 → 顺序执行, 不并行。 +## 子代理调用 +- Task(builder): 开发任务 +- Task(validator): 验证任务 +- Task(explorer): 调研任务 +- `claude agents` 查看运行状态 diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index defc5c18..17fcde1b 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -1,33 +1,36 @@ --- name: brainstorm -description: 苏格拉底式需求精炼 — R₀b 阶段 +description: 需求头脑风暴 — R₀b 阶段, 探索方案空间 context: main --- +## 触发: Path B+ 任务开始时 (自动加载) -## 触发 -Path B+ 任务启动时, RIPER R₀b 阶段。 +## 步骤 +1. augment-context-engine 搜索相关代码和依赖 +2. 读 .ai_state/knowledge.md 了解历史经验和项目规范 +3. 生成 Spec 需求模板 (写入 design.md 顶部): + - 功能需求 (MUST/SHOULD/COULD) + - 非功能需求 (性能/安全/兼容性) + - 约束条件 (技术栈/时间/依赖) + - 验收标准 (可测试的完成条件) +4. 生成 2-3 个候选方案, 每个包含: + 方案描述 / 优劣势 / 预估工作量 / 技术风险 +5. 输出到 .ai_state/design.md +6. cunzhi [DESIGN_DIRECTION] 让用户选择方向 -## 工具 +## Spec 模板格式 +```markdown +## Spec: {需求标题} +### 功能需求 +- [MUST] ... +- [SHOULD] ... +### 非功能需求 +- 性能: ... +- 安全: ... +### 约束 +- ... +### 验收标准 +- [ ] ... +``` -| 工具 | 类型 | 调用方式 | -|:---|:---|:---| -| augment-context-engine | MCP | 搜索现有代码理解项目结构 | -| mcp-deepwiki | MCP | 查候选库文档验证方案 | -| cunzhi | MCP | [DESIGN_DIRECTION] 确认方向 | -| superpowers brainstorming | Plugin | 自动: 苏格拉底提问方法论 | - -## 流程 - -1. augment-context-engine 搜索项目关键文件, 建立上下文 -2. 读 .ai_state/conventions.md 和 .knowledge/pitfalls.md -3. **逐个提问** (一次一问, 优先选择题, YAGNI 原则) -4. 提出 2-3 方案, deepwiki 验证候选技术可行性 -5. **分段呈现** (每段 ≤200 字, 逐段确认) -6. 输出到 .ai_state/design.md -7. cunzhi [DESIGN_DIRECTION] 确认 - -## 输出 -`.ai_state/design.md` — 下游被 R/D 阶段和 plan-first 消费。 - -## 降级 -MCP 不可用 → 直接对话提问, 手动记录到 design.md。 +不可用时: 直接基于需求分析, 跳过代码搜索 diff --git a/.claude/skills/code-quality/SKILL.md b/.claude/skills/code-quality/SKILL.md deleted file mode 100644 index 65ddaced..00000000 --- a/.claude/skills/code-quality/SKILL.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: code-quality -description: 代码审查编排 — T/V 阶段 -context: main ---- - -## 工具编排 - -| 工具 | 类型 | 触发 | 调用方式 | -|:---|:---|:---|:---| -| code-review | Plugin | T 阶段自动 | 自然语言: "审查以上变更" | -| security-guidance | Plugin | Path C+ | 自然语言: "检查安全问题" | -| pr-review-toolkit | Plugin | V 阶段 PR 时 | 自然语言: "准备 PR 审查" | -| superpowers review | Plugin Skill | T 阶段 | 自动触发 | - -## 审查维度 -不重复 Superpowers 方法论。只补充 VibeCoding 特有规则: -- design.md 中的决策是否被正确实现 -- conventions.md 中的约定是否被遵守 -- .knowledge/pitfalls.md 中的陷阱是否被规避 diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md new file mode 100644 index 00000000..50df10e4 --- /dev/null +++ b/.claude/skills/code-review/SKILL.md @@ -0,0 +1,18 @@ +--- +name: code-review +description: 代码审查 — T 阶段辅助 +context: main +--- +## 触发: T 阶段, verification 之后 + +## 审查维度 +1. 逻辑正确性: 边界条件、错误处理、并发安全 +2. 可读性: 命名清晰、函数职责单一、注释合理 +3. 性能: 无 N+1 查询、无不必要的循环 +4. 安全: 无注入、无硬编码密钥 +5. 测试: 测试有意义, 不只是刷覆盖率 +6. 优雅: "如果重新实现, 我会这样写吗?" + +## 输出格式 +每个问题: 文件+行号 / MUST-FIX|SHOULD-FIX|NIT / 问题描述 / 修复建议 +无问题: "APPROVED — no issues found" diff --git a/.claude/skills/context7/SKILL.md b/.claude/skills/context7/SKILL.md index ec3fb480..572ceca1 100644 --- a/.claude/skills/context7/SKILL.md +++ b/.claude/skills/context7/SKILL.md @@ -1,22 +1,19 @@ --- name: context7 -description: 库文档按需拉取 — 贯穿 R₀b/R/D/E +description: 库文档按需拉取 context: main --- -## 调用 +查询依赖库文档时: -``` -优先: mcp-deepwiki 查询 (MCP) -备选: npx ctx7 resolve {库名} (CLI) -降级: web search 搜索官方文档 -``` +1. 优先: ctx7 和 mcp-deepwiki 查询 +2. 降级: WebSearch 搜索官方文档 ## 使用时机 -- **R₀b**: 方案对比时拉取候选库文档, 验证 API 满足需求 -- **R**: 深入调研已选技术栈的具体用法和限制 -- **D**: 查 API 细节确认接口设计可行 -- **E**: 不确定 API 用法时即时查询 +- R₀b brainstorm: 候选库文档对比 +- R 研究: 深入调研技术栈 +- D 设计: 确认 API 接口可行 +- E 开发: 不确定用法时即时查询 不预加载, 按需拉取, 仅取所需章节。 diff --git a/.claude/skills/cunzhi/SKILL.md b/.claude/skills/cunzhi/SKILL.md deleted file mode 100644 index f1b4e524..00000000 --- a/.claude/skills/cunzhi/SKILL.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -name: cunzhi -description: 寸止检查点协议 — 全阶段 -context: main ---- - -## 检查点清单 - -| 检查点 | 阶段 | Path | 含义 | -|:---|:---|:---|:---| -| [DESIGN_DIRECTION] | R₀b | B+ | 用户选择技术方向 | -| [DESIGN_READY] | D | B+ | 设计方案确认 | -| [PLAN_CONFIRMED] | P | B+ | 执行计划确认 | -| [MILESTONE_CHECK] | E | C+ | 阶段性里程碑确认 (每 3-5 任务) | -| [SECURITY_PASSED] | T | C+ | 安全审查通过 | -| [DELIVERY_CONFIRMED] | V | ALL | 最终交付确认 | - -## 调用方式 - -``` -优先: cunzhi MCP → 弹出确认界面, AI 真正暂停等待 -降级: 对话确认 → 直接问用户, 等回复再继续 -``` - -不可跳过确认本身。如果 cunzhi MCP 不可用, 必须用对话方式等待用户回复。 - -## 规则 -- Path A 只需 [DELIVERY_CONFIRMED] -- Path B 需要 [DESIGN_DIRECTION] + [DESIGN_READY] + [PLAN_CONFIRMED] + [DELIVERY_CONFIRMED] -- Path C+ 需要全部检查点 diff --git a/.claude/skills/e2e-testing/SKILL.md b/.claude/skills/e2e-testing/SKILL.md index 3b90d770..e14f3d50 100644 --- a/.claude/skills/e2e-testing/SKILL.md +++ b/.claude/skills/e2e-testing/SKILL.md @@ -1,21 +1,16 @@ --- name: e2e-testing -description: Playwright E2E 测试 — T 阶段 (Path C+) +description: 端到端测试 — Path C/D 的 T 阶段 context: main --- +## 触发: Path C/D 的 T(测试) 阶段 -## 触发 -Path C+ 的 T 阶段, 且项目有前端或 API 端点。 - -## 流程 - -1. 检查 playwright 是否安装, 未安装则 `npm install -D @playwright/test` -2. 从 plan.md 提取关键用户流 -3. 编写或更新 E2E 测试 -4. `npx playwright test` 执行 -5. 失败 → 截图保存 → 修复 → 重跑 (最多 3 轮) -6. 结果写入 verified.md +## 步骤 +1. 检查 Playwright 配置 (playwright.config.ts) +2. 调用 e2e-runner 子代理执行测试 +3. 收集结果: 通过率 + 失败详情 + 截图 +4. 失败 → 反馈给 builder 修复 → 重测 +5. 全部通过 → cunzhi [TESTS_PASSED] ## 降级 -无 Playwright → 用 curl/fetch 做 API 冒烟测试。 -纯 CLI 工具 → 跳过 E2E, 只跑单测。 +Playwright 不可用 → 手动功能验证 + 用户确认 diff --git a/.claude/skills/kaizen/SKILL.md b/.claude/skills/kaizen/SKILL.md new file mode 100644 index 00000000..de3a1d11 --- /dev/null +++ b/.claude/skills/kaizen/SKILL.md @@ -0,0 +1,23 @@ +--- +name: kaizen +description: 持续改进 — V 阶段, 交付后自动复盘经验沉淀 +context: main +--- +## 触发: V(验收) 阶段, delivery-gate 通过后 (自动加载) + +## 步骤 +1. `git diff --stat HEAD~{n}..HEAD` 分析本次变更范围 +2. 回顾开发过程中遇到的问题: + - 哪些决策是正确的? 为什么? + - 哪些地方浪费了时间? 根因是什么? + - 有什么模式可以复用? +3. 提炼输出: + - **knowledge.md**: 可复用的项目模式和决策 + - **lessons.md**: 错误教训和陷阱 (避免重蹈) + - **conventions.md**: 如发现新的编码规范需更新 +4. 简洁记录, 每条 ≤2 行, 重质不重量 + +## 原则 +- 只记录有价值的、可操作的经验 +- 不记录通用编程常识 (AI 已知) +- 格式: `[日期] 领域: 经验描述` diff --git a/.claude/skills/knowledge/SKILL.md b/.claude/skills/knowledge/SKILL.md deleted file mode 100644 index 0397d105..00000000 --- a/.claude/skills/knowledge/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: knowledge -description: 经验管理 — V 阶段沉淀, R 阶段读取 -context: main ---- - -## .knowledge/ 目录 - -| 文件 | 内容 | 写入时机 | 读取时机 | -|:---|:---|:---|:---| -| patterns.md | 成功的解决模式 | V 阶段 | R₀b 阶段 | -| pitfalls.md | 踩过的坑和规避方法 | V 阶段 / 出错时 | R₀b/R 阶段 | -| decisions.md | 架构决策记录 (ADR) | D 阶段 | R 阶段 | -| tools.md | 工具使用经验和配置 | 任何时候 | R 阶段 | - -## 写入格式 - -```markdown -## [日期] [标题] - -**场景**: 什么情况下遇到的 -**方案**: 怎么解决的 -**效果**: 结果如何 -``` - -## 规则 -- V 阶段结束前, 至少更新一个 .knowledge/ 文件 -- 出错重试超过 2 次, 立即写入 pitfalls.md -- ADR 记录不可删除, 只追加 diff --git a/.claude/skills/plan-first/SKILL.md b/.claude/skills/plan-first/SKILL.md index 8b98d9ac..ab19b85d 100644 --- a/.claude/skills/plan-first/SKILL.md +++ b/.claude/skills/plan-first/SKILL.md @@ -1,24 +1,20 @@ --- name: plan-first -description: 强制先规划后执行 — P 阶段 +description: 强制先规划后执行 — 基于 design.md 生成计划 context: main --- +## 触发: Path B+ 任务, brainstorm 完成后 -## 触发 -Path B+ 任务, D 阶段完成后。 - -## 流程 - -1. 读 .ai_state/design.md (brainstorm/R/D 阶段输出) -2. 使用 /plan 进入规划模式 +## 步骤 +1. 读 .ai_state/design.md 作为规划输入 +2. 进入规划模式 (分析 design.md, 分解为可执行任务) 3. context7 查询任务涉及的库文档, 确保技术细节准确 -4. 输出 .ai_state/plan.md: - - 任务列表 (编号 T-001, T-002...) - - 依赖关系 (T-003 depends on T-001) - - 时间预估 - - Path C+: 子代理分配 +4. 输出到 .ai_state/plan.md: + - [ ] 任务列表 (checkbox 格式) + - 依赖关系 + - 预估时间 + - 子代理分配 (Path C+) 5. cunzhi [PLAN_CONFIRMED] 确认后才能写代码 -6. plan.md 中未完成任务不能关闭 session (delivery-gate 检查) +6. plan.md 未完成任务 → delivery-gate 阻塞 -## 管道 -design.md (上游) → plan-first → plan.md (下游) → E 阶段消费 +## 管道: brainstorm → context7 → plan-first → E diff --git a/.claude/skills/quickstart/SKILL.md b/.claude/skills/quickstart/SKILL.md index f13fde94..fe399014 100644 --- a/.claude/skills/quickstart/SKILL.md +++ b/.claude/skills/quickstart/SKILL.md @@ -1,39 +1,18 @@ --- name: quickstart -description: 新手引导流 — 首次使用或不知如何开始时 +description: 新手引导 — 首次使用 VibeCoding 的引导流程 context: main --- +## 触发: 无 .ai_state/ 目录时 -## 触发条件 +## 步骤 +1. 欢迎: "VibeCoding Kernel v9.1.0 — AI 编程协作框架" +2. 检测项目类型 (package.json/Cargo.toml/go.mod/pyproject.toml) +3. 引导执行 /vibe-init 初始化 +4. 简要说明: + - /vibe-dev {需求} 开始开发 + - /vibe-status 查看进度 + - /vibe-resume 中断恢复 +5. 提示: 复杂任务会自动路由到合适的工作流 -1. vibe-init 检测到无 .ai_state/ 目录 -2. 用户说"不知道怎么开始"、"怎么用"、"help" -3. 首次在项目中使用 VibeCoding - -## 流程 - -1. **检测项目类型** - - 有 package.json → Node.js 项目 - - 有 requirements.txt/pyproject.toml → Python - - 有 go.mod → Go - - 空目录 → 新项目, 问用户想做什么 - -2. **引导用户描述需求** - ``` - 👋 VibeCoding 已就绪! - - 告诉我你想做什么, 比如: - · "修复登录页面的样式问题" → 我会快速修复 (Path A) - · "给项目加个搜索功能" → 我会完整规划再开发 (Path B) - · "重构整个认证系统" → 我会拆分任务并行开发 (Path C) - - 或者直接描述你的需求, 我来判断复杂度。 - ``` - -3. **展示执行计划预览** - 自动路由到 P.A.C.E., 展示计划, cunzhi 确认后开始。 - -## 设计原则 -- 不暴露 VibeCoding 内部术语 (RIPER/P.A.C.E./Superpowers) -- 用户只需要说"做什么", 系统负责"怎么做" -- 提供具体示例, 降低认知门槛 +## 原则: 不要解释内部机制 (RIPER/PACE), 只告诉用户怎么用 diff --git a/.claude/skills/security-review/SKILL.md b/.claude/skills/security-review/SKILL.md deleted file mode 100644 index 54694258..00000000 --- a/.claude/skills/security-review/SKILL.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: security-review -description: 安全审查清单 — T 阶段 (Path C+) -context: main ---- - -## 触发 -Path C+ 的 T 阶段。 - -## 工具 - -| 工具 | 调用方式 | -|:---|:---| -| security-guidance | Plugin, 自然语言: "安全审查当前变更" | -| security-auditor agent | 子代理 (background), Path C+ 自动启动 | - -## 检查项 (VibeCoding 补充) - -- [ ] 无硬编码密钥/Token/密码 -- [ ] SQL 查询使用参数化 (无字符串拼接) -- [ ] 用户输入已做 XSS 防护 -- [ ] API 端点有认证/授权检查 -- [ ] 敏感数据不出现在日志中 -- [ ] 依赖无已知漏洞 (`npm audit`) - -## 输出 -cunzhi [SECURITY_PASSED] 确认后写入 verified.md。 diff --git a/.claude/skills/smart-archive/SKILL.md b/.claude/skills/smart-archive/SKILL.md deleted file mode 100644 index c392d9cc..00000000 --- a/.claude/skills/smart-archive/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: smart-archive -description: 智能压缩归档 — V 阶段 -context: main ---- - -## 触发 -V 阶段 [DELIVERY_CONFIRMED] 后。 - -## 流程 - -1. 将 .ai_state/ 中的完成文件移动到 .ai_state/archive/{date}/ -2. 保留 conventions.md (跨任务持续) -3. 清理 session.md (为下次任务准备) -4. 不清理 .knowledge/ (永久持续) - -## 与 /compact 关系 -/compact 是 Claude Code 内置的上下文压缩。 -smart-archive 是 VibeCoding 的任务归档。两者互补, 不冲突。 - -## 降级 -归档目录创建失败 → 将状态文件内容追加到 conventions.md 底部保留, 不丢失。 diff --git a/.claude/skills/tdd/SKILL.md b/.claude/skills/tdd/SKILL.md index 42eb7d63..c65bf2e8 100644 --- a/.claude/skills/tdd/SKILL.md +++ b/.claude/skills/tdd/SKILL.md @@ -1,24 +1,33 @@ --- name: tdd -description: TDD 分级策略 — E 阶段 +description: 测试驱动开发 — E 阶段, 先写测试后实现 (强制执行) context: main --- +## 触发: E(执行) 阶段 (自动加载) -## 分级 +## 铁律: RED → GREEN → REFACTOR +**写功能代码前必须先有失败的测试。PostToolUse hook 会检查。** -| Path | 策略 | 覆盖率 | -|:---|:---|:---| -| A | 改了什么手动验证 | 不强制 | -| B | 关键路径写测试, 边界场景 | ≥60% 变更代码 | -| C+ | 先写测试再实现, 全 TDD | ≥80% | +## 分级策略 +- **Level 1** (Path A): 功能验证, 关键路径有测试即可 +- **Level 2** (Path B): 单元+集成, 严格 RED→GREEN→REFACTOR +- **Level 3** (Path C+): + E2E, 覆盖率 >80% -## 流程 (Path B+) +## 强制流程 (Level 2+) +1. 读 plan.md 当前任务 +2. 写失败测试 (RED) — **必须先看到测试失败** +3. 写最小实现通过测试 (GREEN) — **只写刚好让测试通过的代码** +4. 重构 (REFACTOR) — 改善结构, 测试保持绿色 +5. 更新 doing.md 看板 (TODO→DOING→DONE) +6. git commit -1. 从 plan.md 提取当前任务的验收标准 -2. 先写测试 (或至少测试桩) -3. 实现代码 -4. 运行测试, 失败→修复→再跑 (最多 3 轮) -5. 3 轮仍失败 → 标记"需要人工介入", cunzhi 通知 +## 违规处理 +如果写了源代码但没有对应测试: +- PostToolUse prompt hook 会提醒 +- 必须补写测试后才能继续 -## 降级 -测试框架不存在 → 先 `npm install` 安装, 或用断言脚本替代。 +## 测试命令自动检测 +package.json scripts.test → npm test +pytest.ini/pyproject.toml → pytest +Cargo.toml → cargo test +go.mod → go test ./... diff --git a/.claude/skills/verification/SKILL.md b/.claude/skills/verification/SKILL.md index e108e73a..9d5dd8ab 100644 --- a/.claude/skills/verification/SKILL.md +++ b/.claude/skills/verification/SKILL.md @@ -1,30 +1,20 @@ --- name: verification -description: 分级验证清单 — T 阶段 +description: 代码验证 — T 阶段 context: main --- +## 触发: T(测试) 阶段 -## 分级清单 +## 检查清单 +1. 所有测试通过 (自动检测测试命令) +2. lint 通过 (eslint/ruff/clippy) +3. 类型检查通过 (tsc/mypy/cargo check) +4. 无 TODO/FIXME 残留 +5. .ai_state/conventions.md 规范符合 -### Path A (最小验证) -- [ ] 修改的功能可正常运行 -- [ ] lint 无新增错误 +## Path 差异 +- Path A: 检查 1 即可 +- Path B: 检查 1-5 + 输出 verified.md +- Path C+: + 调用 validator 子代理 -### Path B (标准验证) -- [ ] Path A 全部 -- [ ] 单测通过 (`npm test` 或等效) -- [ ] 类型检查通过 (`tsc --noEmit` 或等效) -- [ ] plan.md 中所有任务标记 DONE - -### Path C+ (完整验证) -- [ ] Path B 全部 -- [ ] E2E 测试通过 (skills/e2e-testing) -- [ ] 安全审查通过 (skills/security-review) -- [ ] 无硬编码密钥/Token -- [ ] 性能无明显退化 - -## 输出 -`.ai_state/verified.md` — 记录验证结果。 - -## 注意 -Path A 不检查 plan.md (因为 Path A 没有 P 阶段)。 +## 输出: .ai_state/verified.md (通过项目 + 发现问题) diff --git a/.claude/templates/ai-state/archive.md b/.claude/templates/ai-state/archive.md new file mode 100644 index 00000000..1df28d34 --- /dev/null +++ b/.claude/templates/ai-state/archive.md @@ -0,0 +1,3 @@ +# archive + + diff --git a/.claude/templates/ai-state/conventions.md b/.claude/templates/ai-state/conventions.md index d281d64e..10c6b29e 100644 --- a/.claude/templates/ai-state/conventions.md +++ b/.claude/templates/ai-state/conventions.md @@ -1,13 +1,8 @@ -# Project Conventions - -## 项目信息 -- 名称: -- 类型: -- 语言: -- 框架: - -## 代码风格 - -## 命名约定 - -## 禁止事项 +# Conventions + +## 语言: {TypeScript/Python/Rust/Go} +## 框架: {Next.js/FastAPI/Actix/...} +## 测试: {Jest/Pytest/Cargo test/...} +## 代码风格: {ESLint配置/Ruff配置/...} +## 命名规范: {camelCase/snake_case/...} +## Git 分支策略: {trunk-based/gitflow/...} diff --git a/.claude/templates/ai-state/design.md b/.claude/templates/ai-state/design.md index 51e5d15d..99f28787 100644 --- a/.claude/templates/ai-state/design.md +++ b/.claude/templates/ai-state/design.md @@ -1,13 +1,3 @@ -# Design Document - -## 需求理解 - -## 方案对比 - -| 方案 | 优点 | 缺点 | 选择 | -|:---|:---|:---|:---| - -## 技术决策 - -## 确认状态 -- [ ] cunzhi [DESIGN_READY] +# design + + diff --git a/.claude/templates/ai-state/doing.md b/.claude/templates/ai-state/doing.md index 08e06002..9ff51e08 100644 --- a/.claude/templates/ai-state/doing.md +++ b/.claude/templates/ai-state/doing.md @@ -1,7 +1,7 @@ -# Task Progress - +# Doing (看板) ## TODO - +- {待做任务} ## DOING - +- 🔄 {进行中任务} ## DONE +- ✅ {已完成任务} diff --git a/.claude/templates/ai-state/knowledge.md b/.claude/templates/ai-state/knowledge.md new file mode 100644 index 00000000..d703239b --- /dev/null +++ b/.claude/templates/ai-state/knowledge.md @@ -0,0 +1,6 @@ +# Knowledge + + +## 项目模式 +## 已知陷阱 +## 技术决策记录 diff --git a/.claude/templates/ai-state/lessons.md b/.claude/templates/ai-state/lessons.md new file mode 100644 index 00000000..a07df0a8 --- /dev/null +++ b/.claude/templates/ai-state/lessons.md @@ -0,0 +1,4 @@ +# Lessons + + + diff --git a/.claude/templates/ai-state/plan.md b/.claude/templates/ai-state/plan.md index 3e76d388..869a06ea 100644 --- a/.claude/templates/ai-state/plan.md +++ b/.claude/templates/ai-state/plan.md @@ -1,14 +1,9 @@ -# Execution Plan - +# Plan + +## 需求: {一句话} +## 预估: {时间} ## 任务列表 - -- [ ] T-001: -- [ ] T-002: -- [ ] T-003: - -## 依赖关系 - -## 时间预估 - -## 确认状态 -- [ ] cunzhi [PLAN_CONFIRMED] +- [ ] 任务1: {描述} — {预估} — {子代理: builder/手动} +- [ ] 任务2: {描述} — {预估} — {依赖: 任务1} +## 技术决策 +- {决策1}: {原因} diff --git a/.claude/templates/ai-state/review.md b/.claude/templates/ai-state/review.md index 0da1f8a6..974b2330 100644 --- a/.claude/templates/ai-state/review.md +++ b/.claude/templates/ai-state/review.md @@ -1,6 +1,3 @@ -# Review - -## 代码审查结果 - -## 交付确认 -- [ ] cunzhi [DELIVERY_CONFIRMED] +# review + + diff --git a/.claude/templates/ai-state/session.md b/.claude/templates/ai-state/session.md index 54e79d0a..be53b332 100644 --- a/.claude/templates/ai-state/session.md +++ b/.claude/templates/ai-state/session.md @@ -1,6 +1,7 @@ # Session - -- path: -- current_phase: -- started_at: -- task_summary: + +## 项目: {项目名} +## 当前阶段: {R₀/R/D/P/E/T/V} +## Path: {A/B/C/D} +## 需求摘要: {一句话} +## 更新时间: {时间戳} diff --git a/.claude/templates/ai-state/verified.md b/.claude/templates/ai-state/verified.md index d91bd27c..6b40dd22 100644 --- a/.claude/templates/ai-state/verified.md +++ b/.claude/templates/ai-state/verified.md @@ -1,11 +1,3 @@ -# Verification Results - -## 测试结果 -- [ ] 单测通过 -- [ ] 类型检查通过 -- [ ] lint 无错 - -## 安全检查 (Path C+) -- [ ] 无硬编码密钥 -- [ ] SQL 参数化 -- [ ] XSS 防护 +# verified + + diff --git a/.claude/templates/knowledge/decisions.md b/.claude/templates/knowledge/decisions.md deleted file mode 100644 index 4b58dca3..00000000 --- a/.claude/templates/knowledge/decisions.md +++ /dev/null @@ -1,10 +0,0 @@ -# 架构决策记录 (ADR) - -## 格式 - -### ADR-001: [标题] -**日期**: -**状态**: accepted / deprecated -**上下文**: 为什么需要做这个决策 -**决策**: 选择了什么 -**后果**: 带来的影响 diff --git a/.claude/templates/knowledge/patterns.md b/.claude/templates/knowledge/patterns.md deleted file mode 100644 index 4470a857..00000000 --- a/.claude/templates/knowledge/patterns.md +++ /dev/null @@ -1,10 +0,0 @@ -# 成功模式 - -记录有效的解决方案, 供后续任务参考。 - -## 格式 - -### [日期] [标题] -**场景**: -**方案**: -**效果**: diff --git a/.claude/templates/knowledge/pitfalls.md b/.claude/templates/knowledge/pitfalls.md deleted file mode 100644 index e2a0a602..00000000 --- a/.claude/templates/knowledge/pitfalls.md +++ /dev/null @@ -1,11 +0,0 @@ -# 已知陷阱 - -记录踩过的坑, 避免重复犯错。 - -## 格式 - -### [日期] [标题] -**问题**: -**原因**: -**解决**: -**预防**: diff --git a/.claude/templates/knowledge/tools.md b/.claude/templates/knowledge/tools.md deleted file mode 100644 index 0241a951..00000000 --- a/.claude/templates/knowledge/tools.md +++ /dev/null @@ -1,10 +0,0 @@ -# 工具使用经验 - -记录项目中使用的工具配置和注意事项。 - -## 格式 - -### [工具名] -**版本**: -**配置**: -**注意**: diff --git a/.claude/workflows/pace.md b/.claude/workflows/pace.md index dce92836..84d71c83 100644 --- a/.claude/workflows/pace.md +++ b/.claude/workflows/pace.md @@ -1,79 +1,43 @@ -# P.A.C.E. 复杂度路由 v8.9 +# P.A.C.E. 复杂度路由 (v9.1.0) -## 路由判定 +## 评估维度 +- 文件数 (1 / 2-10 / 10-50 / 50+) +- 预估时间 (<30min / 6-12h / 1-3天 / 1周+) +- 架构影响 (无 / 局部 / 跨模块 / 全局) -分析用户输入, 按以下规则选择 Path: +## Path A — 快速修复 (≤30min, 1-2 文件) +加载: CLAUDE.md + rules.md (~130L) +阶段: R(轻) → E → T(轻) → V +自动 Skills: [R] context7 | [E] tdd(L1) | [T] verification | [V] kaizen +检查点: cunzhi [DELIVERY_CONFIRMED] +注意: 无 plan.md, 无 design.md, delivery-gate 跳过严格检查 -| 信号 | Path A | Path B | Path C | Path D | -|:---|:---|:---|:---|:---| -| 文件数 | 1-2 | 3-10 | 10+ | 20+ | -| 预估时间 | ≤30 min | 6-12h | 1-3 周 | 3+ 周 | -| 关键词 | 修/改/加/删 | 做/实现/开发 | 重构/迁移/系统 | 架构/平台/全栈 | -| 描述长度 | ≤50 字 | 50-200 字 | 200+ 字 | 200+ 字+多模块 | -| 需求数 | 1 | 2-5 | 5-15 | 15+ | +## Path B — 计划开发 (6-12h, 2-10 文件) +加载: + workflows + 6 skills (~540L) +阶段与自动 Skills: + R₀b: **brainstorm** → spec + design.md → cunzhi [DESIGN_DIRECTION] + R: augment-context/deepwiki → **context7** → 更新 design.md + D: **context7** 查 API → design.md 终稿 → cunzhi [DESIGN_READY] + P: **plan-first** → plan.md → cunzhi [PLAN_CONFIRMED] + E: **tdd**(L2) → doing.md 看板 + T: **verification** + **code-review** → verified.md + V: delivery-gate + LLM 审查 → **kaizen** → cunzhi [DELIVERY_CONFIRMED] -> 不确定时: 问用户, 不猜。用 cunzhi 确认 Path 选择。 +## Path C — 系统开发 (1-3 天, 10-50 文件) +加载: + agent-teams + e2e-testing (~700L) +同 Path B + : + E: **agent-teams** 并行 (builder×N / validator / explorer) + T: + **e2e-testing** (Playwright) → cunzhi [TESTS_PASSED] + V: 按功能分 commit + **kaizen** -## 分级加载 +## Path D — 企业级 (1周+, 50+ 文件) +同 Path C + : + E: + e2e-runner + security-auditor 子代理 + T: + security-review → cunzhi [SECURITY_PASSED] + V: 分 PR 交付, 每个 PR 独立审查 + **kaizen** -### Path A — 敏捷 (≤30 min) - -``` -加载: CLAUDE.md + rules/rules.md -跳过: brainstorm, plan-first, agent-teams, security-review -RIPER 节点: R(轻) → E → T(轻) → V(cunzhi) → Done -状态文件: session.md + doing.md (最小集) -``` - -💡 **给新手**: 这是"改一行 CSS"、"修个 bug"、"加个字段"级别的任务。 - -### Path B — 协作 (6-12h) - -``` -加载: CLAUDE.md + rules + pace + riper-7 + 相关 skills -RIPER 节点: R₀b → R → D → P → E → T → V → Done -skills: brainstorm, context7, plan-first, tdd, verification, code-quality -确认点: [DESIGN_READY] [PLAN_CONFIRMED] [DELIVERY_CONFIRMED] -``` - -💡 **给新手**: 这是"做个登录功能"、"实现搜索"、"添加支付模块"级别。 - -### Path C — 系统 (1-3 周) - -``` -加载: 全量 -RIPER 节点: 同 Path B + 并行分工 -额外: agent-teams (worktree 隔离), e2e-testing, security-review -子代理: builder × N + validator + explorer (background) -确认点: 同 Path B + [SECURITY_PASSED] -``` - -💡 **给新手**: 这是"重构认证系统"、"数据库迁移"、"微服务拆分"级别。 - -### Path D — 长期 (3+ 周) - -``` -加载: 同 Path C -额外: 按周拆分里程碑, 每个里程碑 = 一个 Path B/C 子任务 -看板: 里程碑级 kanban + 任务级 kanban -smart-archive: 每个里程碑归档一次 -``` - -💡 **给新手**: 这是"从零搭建一个平台"、"全栈重写"级别。很少用到。 - -## 路由输出格式 - -选定 Path 后, 向用户展示: - -``` -📊 任务分析 -├─ 复杂度: Path B (协作级) -├─ 预估: ~8 小时 -├─ 文件涉及: ~6 个 -├─ 关键技术: React + Supabase Auth -└─ 执行计划: R₀b(头脑风暴) → R(调研) → D(设计) → P(规划) → E(开发) → T(测试) → V(验收) - -确认后开始? -``` - -然后调用 cunzhi 等待确认。 +## 路径选择规则 +1. 默认 Path A, 除非满足升级条件 +2. 用户明确说 "简单修一下" → 不要升级到 B +3. 不确定 → 问用户确认复杂度 +4. 可用 /fork 并行探索多个方案 (Path B+ brainstorm 阶段) diff --git a/.claude/workflows/riper-7.md b/.claude/workflows/riper-7.md index 680d5e4c..6efd0204 100644 --- a/.claude/workflows/riper-7.md +++ b/.claude/workflows/riper-7.md @@ -1,157 +1,72 @@ -# RIPER-7 工程编排 v8.9 +# RIPER-7 阶段编排 (v9.1.0) -## 统一工具调度表 +## 阶段流: R₀ → R → D → P → E → T → V -| 阶段 | VibeCoding Skill | Plugin | MCP | 状态文件 | -|:---|:---|:---|:---|:---| -| R₀b 头脑风暴 | brainstorm | superpowers (brainstorming) | augment-context, deepwiki | design.md | -| R 研究 | context7 | superpowers (research) | augment-context, deepwiki | design.md (更新) | -| D 设计 | context7 | superpowers (writing-plans) | deepwiki | design.md (终稿) | -| P 规划 | plan-first | superpowers (writing-plans) | — | plan.md | -| E 开发 | tdd, code-quality, agent-teams | feature-dev, frontend-design, hookify | augment-context | doing.md | -| T 测试 | verification, e2e-testing | code-review, security-guidance | — | verified.md | -| V 验收 | smart-archive, knowledge | pr-review-toolkit, commit-commands | cunzhi | review.md | +### R₀ (预研/头脑风暴, Path B+ 独有) +触发: /vibe-dev 且 PACE≥B +**自动加载**: brainstorm skill +工具: augment-context + cunzhi +输入: 用户需求 +输出: .ai_state/design.md (含 spec 需求模板 + 方案草案) +检查点: cunzhi [DESIGN_DIRECTION] +技巧: 可用 /fork 并行探索不同方案方向 -## 阶段详情 +### R (研究) +触发: R₀ 确认后 或 Path A 直接进入 +**自动加载**: context7 skill +工具: augment-context + deepwiki + WebSearch +输入: design.md 或 用户需求 +输出: 更新 design.md (技术细节) ---- +### D (设计, Path B+ 独有) +触发: R 完成 +**自动加载**: context7 skill +输入: design.md +输出: design.md 终稿 (接口定义/数据结构/模块划分) +检查点: cunzhi [DESIGN_READY] -### R₀b — 头脑风暴 (Path B+ only) +### P (规划, Path B+ 独有) +触发: D 确认后 +**自动加载**: plan-first skill +输入: design.md +输出: .ai_state/plan.md (任务列表+依赖+预估+子代理分配) +检查点: cunzhi [PLAN_CONFIRMED] -💡 **本阶段做什么**: 理解需求, 探索方案, 不写代码 -🔧 **自动使用**: augment-context 扫描 → deepwiki 查库 → cunzhi 确认 -⏭️ **下一阶段**: R (研究) +### E (执行) +触发: P 确认后 或 Path A R 完成 +**自动加载**: tdd skill (强制模式) + agent-teams (Path C+) +铁律: **先写测试, 再写实现, 测试红了才能写代码** +输入: plan.md (B+) 或 需求描述 (A) +过程: + - Path A: 直接开发, 功能验证 + - Path B: tdd L2 (RED→GREEN→REFACTOR), doing.md 看板 + - Path C/D: agent-teams 并行, worktree 隔离 +输出: .ai_state/doing.md 更新, 代码变更 +Hook: PostToolUse TDD 检查 (写源码前是否有测试) -``` -步骤: -1. augment-context-engine 搜索现有代码, 理解项目结构 -2. 读 .knowledge/pitfalls.md — 避免重复犯错 -3. 加载 skills/brainstorm — 苏格拉底式逐个提问 -4. deepwiki 查候选技术库文档 -5. 输出 2-3 方案到 .ai_state/design.md -6. cunzhi [DESIGN_DIRECTION] — 用户选择方向 -``` +### T (测试/验证) +触发: E 完成 +**自动加载**: verification + code-review skills +工具: validator 子代理 + code-review skill +输入: 代码变更 +过程: + - Path A: 功能验证 + lint + - Path B: verification + code-review → verified.md + - Path C/D: + e2e-testing + security-review +输出: .ai_state/verified.md +检查点: cunzhi [TESTS_PASSED] (C+: [SECURITY_PASSED]) ---- - -### R — 研究 - -💡 **本阶段做什么**: 深入调研已选方案, 确认技术可行性 -🔧 **自动使用**: context7 拉取库文档 → 对照 design.md 验证 - -``` -步骤: -1. 加载 skills/context7 — 按需拉取相关库文档 -2. 对照 design.md 验证方案可行性 -3. 识别技术风险和依赖 -4. 更新 design.md 中的技术细节 -``` - -Path A 简化: 只做 augment-context 快速扫描, 不输出 design.md。 - ---- - -### D — 设计 - -💡 **本阶段做什么**: 确定技术方案, 输出架构决策 -🔧 **自动使用**: context7 查 API 细节 → design.md 终稿 → cunzhi 确认 - -``` -步骤: -1. context7 查 API 细节, 确认接口设计可行 -2. 写入 .knowledge/decisions.md — ADR 记录 -3. 完成 design.md 终稿 -4. cunzhi [DESIGN_READY] — 用户确认设计 -``` - -Path A 跳过。 - ---- - -### P — 规划 - -💡 **本阶段做什么**: 将设计拆解为可执行的任务列表 -🔧 **自动使用**: plan-first 读 design.md → 生成 plan.md → cunzhi 确认 - -``` -步骤: -1. 加载 skills/plan-first -2. 读 design.md 作为输入 -3. 生成 .ai_state/plan.md: 任务列表 + 依赖 + 预估 + 分工 -4. Path C+: 分配子代理 (builder/validator/e2e-runner) -5. cunzhi [PLAN_CONFIRMED] — 用户确认计划 -``` - -Path A 跳过。Path B: /plan 生成轻量计划。 - ---- - -### E — 执行 - -💡 **本阶段做什么**: 按计划写代码, TDD 驱动 -🔧 **自动使用**: tdd 分级 → code-quality 审查 → agent-teams 并行 - -``` -步骤: -1. 加载 skills/tdd — 按 Path 分级: - - Path A: 改了什么手动验证 - - Path B: 关键路径写测试 - - Path C+: 全覆盖 TDD -2. 逐个执行任务: - - Path A: 直接开始开发 (无 plan.md) - - Path B+: 按 plan.md 中的任务列表逐个执行 -3. 每完成一个: doing.md 更新 TODO→DOING→DONE -4. Path C+: agent-teams 并行 - - builder 在 worktree 中实现 - - validator 在 worktree 中测试 - - explorer (background) 持续扫描依赖 -5. 阶段性 cunzhi 确认 (每 3-5 个任务或关键里程碑) -``` - ---- - -### T — 测试 - -💡 **本阶段做什么**: 验证代码质量, 跑测试, 安全检查 -🔧 **自动使用**: verification 分级清单 → e2e-testing → code-review plugin - -``` -步骤: -1. 加载 skills/verification — 按 Path 分级: - - Path A: 功能验证 + lint - - Path B: + 单测通过 + 类型检查 - - Path C+: + E2E + 安全审查 + 性能 -2. Path B+: 触发 code-review plugin 自动审查 -3. Path C+: 加载 skills/e2e-testing (Playwright) -4. Path C+: 加载 skills/security-review -5. 输出 .ai_state/verified.md -``` - ---- - -### V — 验收 - -💡 **本阶段做什么**: 最终确认, 提交, 归档经验 -🔧 **自动使用**: delivery-gate hook → cunzhi 确认 → smart-archive - -``` -步骤: -1. delivery-gate.cjs 自动检查 (Stop hook): - - plan.md 所有任务 DONE? (Path B+) - - 测试通过? - - lint 无错? -2. 加载 skills/code-quality — 最终审查 -3. cunzhi [DELIVERY_CONFIRMED] — 用户确认交付 -4. 触发 commit-commands plugin — 提交: - - Path A: 单次 commit - - Path B: squash merge - - Path C+: 按功能分 commit -5. 加载 skills/knowledge — 沉淀经验到 .knowledge/ -6. 加载 skills/smart-archive — 归档 .ai_state/ 到 archive/ -``` - -## RIPER 阶段流转规则 - -- 只能前进, 不能跳过 (Path A 的"跳过"是路由决定, 不是运行时跳过) -- 每个阶段完成时更新 session.md 中的 `current_phase` 字段 -- 中断恢复: context-loader.cjs 读 session.md 自动恢复到中断阶段 +### V (验收/交付) +触发: T 通过 +**自动执行**: delivery-gate hook + LLM-as-Judge prompt hook +过程: + 1. delivery-gate 机械检查: plan 无未完成项 + 测试通过 + 2. LLM-as-Judge: 代码质量/测试覆盖/commit 规范/无密钥泄露 + 3. cunzhi [DELIVERY_CONFIRMED] 用户确认 + 4. **Kaizen 复盘** (必须): + a. git diff --stat 分析本次变更范围 + b. 提炼经验教训 → 写入 .ai_state/knowledge.md + c. 发现的陷阱 → 写入 .ai_state/lessons.md + d. 更新 .ai_state/conventions.md (如有新规范) + 5. 归档 → .ai_state/archive.md +输出: 交付完成 + 经验沉淀 diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 00000000..a88678d4 --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,54 @@ +# VibeCoding Kernel v9.1.0 — Codex CLI + +## 铁律 (违反即失败) +1. **先搜后写**: augment-context-engine 搜现有实现 → 不可用时 grep -r +2. **先规后码**: Path B+ 任务必须先 plan.md → cunzhi 确认后才能写代码 +3. **先测后码**: E 阶段写功能代码前必须先写/更新测试 (RED→GREEN→REFACTOR) +4. **不确定就问**: 歧义/架构决策 → cunzhi 向用户确认, 不猜 +5. **不破坏已有**: 改代码前读测试, 改后跑测试, 红了就修 +6. **只改需要改的**: 不重构范围外代码, 不加未要求的功能 +7. **避免过度工程**: 最简方案, YAGNI 优先 +8. **commit 粒度**: 每个逻辑变更独立 commit, conventional commits +9. **交付必复盘**: 完成后必须 diff 分析→提炼 lessons→写入 knowledge.md + +## 工作流 +1. 评估复杂度 → P.A.C.E. 路由 (读 .codex/workflows/pace.md) +2. 按路径执行 RIPER-7 阶段 (读 .codex/workflows/riper-7.md) +3. 各阶段 skills **自动加载** (读 .codex/skills/{name}/SKILL.md) + +## TDD 强制规则 (E 阶段) +写功能代码前必须先有失败的测试。流程: +1. 先写测试文件 → 运行 → 看到红色失败 +2. 再写最小实现 → 运行 → 看到绿色通过 +3. 重构 → 测试保持绿色 +违反时: 停下, 补写测试, 再继续 + +## Kaizen 复盘规则 (V 阶段) +交付后必须执行: +1. `git diff --stat` 回顾变更范围 +2. 提炼经验 → .ai_state/knowledge.md +3. 记录陷阱 → .ai_state/lessons.md + +## 状态持久化 +.ai_state/ 目录: session → design → plan → doing → verified → review → archive +模板位于 .codex/templates/ai-state/ + +## MCP 降级 +augment-context 不可用→grep | cunzhi 不可用→对话确认 | deepwiki 不可用→web search + +## Codex 专属能力 +- /review: 原生代码审查 (T 阶段集成) +- /plan: 原生规划模式 (P 阶段集成) +- /statusline: 配置 TUI 底栏显示当前阶段和进度 +- multi_agent + collaboration_modes: 多代理并行 (Path C+) +- [agents] 角色定义: builder / reviewer / explorer (config.toml) +- Profiles: `codex --profile dev|ci|review` 切换预设 +- spawn_agents_on_csv: 批量多代理分派 +- /model: gpt-5.4 (默认) / gpt-5.3-codex / gpt-5.3-codex-spark (快速) + +## 并行工作规范 (Path C/D) +1. 读 plan.md → 识别无依赖任务组 +2. 为每组指派 agent 角色 (Codex 自动编排) +3. 无依赖任务并行, 有依赖串行 +4. 同文件不并行修改 +5. 完成后合并 + /review 审查 diff --git a/.codex/agents/builder.toml b/.codex/agents/builder.toml new file mode 100644 index 00000000..39c622f7 --- /dev/null +++ b/.codex/agents/builder.toml @@ -0,0 +1,11 @@ +# VibeCoding builder 角色配置 +model = "gpt-5.3-codex" +model_reasoning_effort = "high" +developer_instructions = """ +你是 Builder — 专注实现, 不做设计决策。 +1. 只修改任务指定的文件范围, 不越界 +2. 写代码前先写/更新测试 (RED→GREEN) +3. 每个子任务: git add → git commit -m "feat: {描述}" +4. 遇到设计决策 → 停止, 报告主代理 +5. 遵循 .ai_state/conventions.md +""" diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 00000000..0f2786f0 --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,8 @@ +# VibeCoding explorer 角色配置 +model = "gpt-5.3-codex-spark" +model_reasoning_effort = "medium" +developer_instructions = """ +你是 Explorer — 只读调研, 绝对不修改文件。 +方法: grep + 文件搜索 → 深入分析 → 输出发现摘要 +参考 .ai_state/knowledge.md 避免重复调研。 +""" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 00000000..a69ad4a9 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,8 @@ +# VibeCoding reviewer 角色配置 +model = "gpt-5.3-codex" +model_reasoning_effort = "high" +developer_instructions = """ +你是 Reviewer — 代码审查, 不修改代码。 +审查维度: 逻辑正确性 / 可读性 / 性能 / 安全 / 测试质量 +输出格式: 文件+行号 / MUST-FIX|SHOULD-FIX|NIT / 问题描述 / 修复建议 +""" diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 00000000..50e0c787 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,96 @@ +# VibeCoding Kernel v9.1.0 — Codex CLI 配置 +model_provider = "custom" +model = "gpt-5.4" +model_reasoning_effort = "xhigh" +suppress_unstable_features_warning = true + +# 危险,可开启 和下面的二选一,上面的代表绝对信任 +# approval_policy = "never" # untrusted|on-request|never +# sandbox_mode = "danger-full-access" # read-only|workspace-write|danger-full-access + +approval_policy = "never" +sandbox_mode = "workspace-write" + +[sandbox_workspace_write] +network_access = true # npm install / pip install 需要网络 + +# Web Search +web_search = "live" + +[features] +multi_agent = true # stable; 多代理编排 +collaboration_modes = true # stable; 协作模式 +shell_snapshot = true # beta; 加速重复命令 +unified_exec = true # beta; PTY-backed 执行 +shell_tool = true # stable; 默认 shell 工具 +apply_patch_freeform = true # experimental; 自由 patch +undo = true # 回滚 Codex 改动; + +[tui] +notifications = true +animations = true + +[profiles.dev] +# 日常开发: 高推理, 交互审批 +model = "gpt-5.4" +model_reasoning_effort = "high" +approval_policy = "on-request" +sandbox_mode = "workspace-write" + +[profiles.ci] +# CI/CD: 全自动, 无审批 +model = "gpt-5.3-codex" +model_reasoning_effort = "medium" +approval_policy = "never" +sandbox_mode = "workspace-write" + +[profiles.review] +# 代码审查: 高推理, 只读 +model = "gpt-5.4" +model_reasoning_effort = "xhigh" +approval_policy = "untrusted" +sandbox_mode = "read-only" + +[agents] +max_threads = 6 +max_depth = 2 +job_max_runtime_seconds = 1800 + +[agents.builder] +description = "实现功能代码。先写测试再写实现, 每个子任务完成后 commit。" +config_file = "./agents/builder.toml" + +[agents.reviewer] +description = "代码审查: 安全、正确性、测试风险。" +config_file = "./agents/reviewer.toml" + +[agents.explorer] +description = "只读搜索分析: 搜索代码库、分析依赖、查找模式。" +config_file = "./agents/explorer.toml" + +[model_providers.custom] +name = "custom" +wire_api = "responses" +requires_openai_auth = true +base_url = "" + +[mcp_servers] + +[mcp_servers.mcp-deepwiki] +type = "stdio" +command = "npx" +args = ["-y", "mcp-deepwiki@latest"] + +[mcp_servers."cunzhi"] +type = "stdio" +command = "寸止" + +[mcp_servers.chrome-devtools] +type = "stdio" +command = "npx" +args = ["-y", "chrome-devtools-mcp@latest"] + +[mcp_servers.augment-context-engine] +type = "stdio" +command = "npx" +args = ["ace-tool-rs", "--base-url", "https://acemcp.heroman.wtf/relay/", "--token", ""] diff --git a/.codex/skills/agent-teams/SKILL.md b/.codex/skills/agent-teams/SKILL.md new file mode 100644 index 00000000..38c95257 --- /dev/null +++ b/.codex/skills/agent-teams/SKILL.md @@ -0,0 +1,28 @@ +--- +name: agent-teams +description: 多代理并行协作 — Path C/D 的 E 阶段 +context: main +--- +## 触发: Path C/D 的 E(执行) 阶段 (自动加载) + +## 前提 +- config.toml [features] multi_agent=true, collaboration_modes=true +- config.toml [agents] 定义了 builder/reviewer/explorer 角色 +- plan.md 中任务已标注可并行/有依赖 + +## 编排策略 +1. 读 plan.md → 识别无依赖的任务组 +2. Codex 自动编排多代理 (基于 [agents] 角色定义) +3. spawn_agents_on_csv 可用于批量分派 +4. 每个子代理独立工作, 完成后合并 + +## 并行规则 +- 无依赖任务: 并行执行 +- 有依赖任务: 串行, 前置完成后触发 +- 同文件不并行修改 +- 完成后 /review 审查合并结果 + +## 角色 +builder: 先测试后实现, 限定范围, 每任务 commit +reviewer: 代码审查, 安全/正确性/测试风险 +explorer: 只读调研, 搜索代码库/分析依赖 diff --git a/.codex/skills/brainstorm/SKILL.md b/.codex/skills/brainstorm/SKILL.md new file mode 100644 index 00000000..b6ecf9b0 --- /dev/null +++ b/.codex/skills/brainstorm/SKILL.md @@ -0,0 +1,21 @@ +--- +name: brainstorm +description: 需求头脑风暴 — R₀b 阶段, 探索方案空间 +context: main +--- +## 触发: Path B+ 任务开始时 (自动加载) + +## 步骤 +1. augment-context-engine 搜索相关代码和依赖 +2. 读 .ai_state/knowledge.md 了解历史经验 +3. 生成 Spec 需求模板 (写入 design.md 顶部): + - 功能需求 (MUST/SHOULD/COULD) + - 非功能需求 (性能/安全/兼容性) + - 约束条件 (技术栈/时间/依赖) + - 验收标准 (可测试的完成条件) +4. 生成 2-3 个候选方案, 每个包含: + 方案描述 / 优劣势 / 预估工作量 / 技术风险 +5. 输出到 .ai_state/design.md +6. cunzhi [DESIGN_DIRECTION] 让用户选择方向 + +不可用时: 直接基于需求分析, 跳过代码搜索 diff --git a/.codex/skills/code-review/SKILL.md b/.codex/skills/code-review/SKILL.md new file mode 100644 index 00000000..50df10e4 --- /dev/null +++ b/.codex/skills/code-review/SKILL.md @@ -0,0 +1,18 @@ +--- +name: code-review +description: 代码审查 — T 阶段辅助 +context: main +--- +## 触发: T 阶段, verification 之后 + +## 审查维度 +1. 逻辑正确性: 边界条件、错误处理、并发安全 +2. 可读性: 命名清晰、函数职责单一、注释合理 +3. 性能: 无 N+1 查询、无不必要的循环 +4. 安全: 无注入、无硬编码密钥 +5. 测试: 测试有意义, 不只是刷覆盖率 +6. 优雅: "如果重新实现, 我会这样写吗?" + +## 输出格式 +每个问题: 文件+行号 / MUST-FIX|SHOULD-FIX|NIT / 问题描述 / 修复建议 +无问题: "APPROVED — no issues found" diff --git a/.codex/skills/context7/SKILL.md b/.codex/skills/context7/SKILL.md new file mode 100644 index 00000000..572ceca1 --- /dev/null +++ b/.codex/skills/context7/SKILL.md @@ -0,0 +1,19 @@ +--- +name: context7 +description: 库文档按需拉取 +context: main +--- + +查询依赖库文档时: + +1. 优先: ctx7 和 mcp-deepwiki 查询 +2. 降级: WebSearch 搜索官方文档 + +## 使用时机 + +- R₀b brainstorm: 候选库文档对比 +- R 研究: 深入调研技术栈 +- D 设计: 确认 API 接口可行 +- E 开发: 不确定用法时即时查询 + +不预加载, 按需拉取, 仅取所需章节。 diff --git a/.codex/skills/e2e-testing/SKILL.md b/.codex/skills/e2e-testing/SKILL.md new file mode 100644 index 00000000..e14f3d50 --- /dev/null +++ b/.codex/skills/e2e-testing/SKILL.md @@ -0,0 +1,16 @@ +--- +name: e2e-testing +description: 端到端测试 — Path C/D 的 T 阶段 +context: main +--- +## 触发: Path C/D 的 T(测试) 阶段 + +## 步骤 +1. 检查 Playwright 配置 (playwright.config.ts) +2. 调用 e2e-runner 子代理执行测试 +3. 收集结果: 通过率 + 失败详情 + 截图 +4. 失败 → 反馈给 builder 修复 → 重测 +5. 全部通过 → cunzhi [TESTS_PASSED] + +## 降级 +Playwright 不可用 → 手动功能验证 + 用户确认 diff --git a/.codex/skills/kaizen/SKILL.md b/.codex/skills/kaizen/SKILL.md new file mode 100644 index 00000000..83cbbf29 --- /dev/null +++ b/.codex/skills/kaizen/SKILL.md @@ -0,0 +1,23 @@ +--- +name: kaizen +description: 持续改进 — V 阶段, 交付后自动复盘经验沉淀 +context: main +--- +## 触发: V(验收) 阶段, 交付确认后 (自动加载) + +## 步骤 +1. `git diff --stat HEAD~{n}..HEAD` 分析变更范围 +2. 回顾开发过程: + - 哪些决策正确? 为什么? + - 哪些地方浪费时间? 根因? + - 可复用的模式? +3. 提炼输出: + - **knowledge.md**: 可复用模式和决策 + - **lessons.md**: 错误教训和陷阱 + - **conventions.md**: 新规范 (如有) +4. 简洁记录, 每条 ≤2 行 + +## 原则 +- 只记录有价值的、可操作的经验 +- 不记录 AI 已知的通用常识 +- 格式: `[日期] 领域: 经验描述` diff --git a/.codex/skills/plan-first/SKILL.md b/.codex/skills/plan-first/SKILL.md new file mode 100644 index 00000000..54391d2e --- /dev/null +++ b/.codex/skills/plan-first/SKILL.md @@ -0,0 +1,20 @@ +--- +name: plan-first +description: 强制先规划后执行 — 基于 design.md 生成计划 +context: main +--- +## 触发: Path B+ 任务, brainstorm 完成后 + +## 步骤 +1. 读 .ai_state/design.md 作为规划输入 +2. 使用 /plan 进入规划模式 +3. context7 查询任务涉及的库文档, 确保技术细节准确 +4. 输出到 .ai_state/plan.md: + - [ ] 任务列表 (checkbox 格式) + - 依赖关系 + - 预估时间 + - 子代理分配 (Path C+) +5. cunzhi [PLAN_CONFIRMED] 确认后才能写代码 +6. plan.md 未完成任务 → delivery-gate 阻塞 + +## 管道: brainstorm → context7 → plan-first → E diff --git a/.codex/skills/quickstart/SKILL.md b/.codex/skills/quickstart/SKILL.md new file mode 100644 index 00000000..293af9b8 --- /dev/null +++ b/.codex/skills/quickstart/SKILL.md @@ -0,0 +1,20 @@ +--- +name: quickstart +description: 新手引导 — 首次使用 VibeCoding 的引导流程 +context: main +--- +## 触发: 无 .ai_state/ 目录时 + +## 步骤 +1. 欢迎: "VibeCoding Kernel v9.1.0 — AI 编程协作框架" +2. 检测项目类型 (package.json/Cargo.toml/go.mod/pyproject.toml) +3. 初始化 .ai_state/ 目录 (从 .codex/templates/ai-state/ 复制模板) +4. 简要说明: + - 直接描述需求即可开始 (自动 P.A.C.E. 路由) + - "查看进度" 或 "当前状态" → 显示看板 + - "继续上次" → 从断点恢复 + - /review → 原生代码审查 + - /plan → 原生规划模式 +5. 提示: 复杂任务会自动路由到合适的工作流 + +## 原则: 不要解释内部机制 (RIPER/PACE), 只告诉用户怎么用 diff --git a/.codex/skills/tdd/SKILL.md b/.codex/skills/tdd/SKILL.md new file mode 100644 index 00000000..386b41cc --- /dev/null +++ b/.codex/skills/tdd/SKILL.md @@ -0,0 +1,29 @@ +--- +name: tdd +description: 测试驱动开发 — E 阶段, 先写测试后实现 (强制执行) +context: main +--- +## 触发: E(执行) 阶段 (自动加载) + +## 铁律: RED → GREEN → REFACTOR +**写功能代码前必须先有失败的测试。** +违反此规则时, 立即停止, 补写测试。 + +## 分级策略 +- **Level 1** (Path A): 功能验证, 关键路径有测试即可 +- **Level 2** (Path B): 单元+集成, 严格 RED→GREEN→REFACTOR +- **Level 3** (Path C+): + E2E, 覆盖率 >80% + +## 强制流程 (Level 2+) +1. 读 plan.md 当前任务 +2. 写失败测试 (RED) → 运行确认失败 +3. 写最小实现 (GREEN) → 运行确认通过 +4. 重构 (REFACTOR) → 测试保持绿色 +5. 更新 doing.md (TODO→DOING→DONE) +6. git commit + +## 测试命令自动检测 +package.json scripts.test → npm test +pytest.ini/pyproject.toml → pytest +Cargo.toml → cargo test +go.mod → go test ./... diff --git a/.codex/skills/verification/SKILL.md b/.codex/skills/verification/SKILL.md new file mode 100644 index 00000000..9d5dd8ab --- /dev/null +++ b/.codex/skills/verification/SKILL.md @@ -0,0 +1,20 @@ +--- +name: verification +description: 代码验证 — T 阶段 +context: main +--- +## 触发: T(测试) 阶段 + +## 检查清单 +1. 所有测试通过 (自动检测测试命令) +2. lint 通过 (eslint/ruff/clippy) +3. 类型检查通过 (tsc/mypy/cargo check) +4. 无 TODO/FIXME 残留 +5. .ai_state/conventions.md 规范符合 + +## Path 差异 +- Path A: 检查 1 即可 +- Path B: 检查 1-5 + 输出 verified.md +- Path C+: + 调用 validator 子代理 + +## 输出: .ai_state/verified.md (通过项目 + 发现问题) diff --git a/.codex/templates/ai-state/archive.md b/.codex/templates/ai-state/archive.md new file mode 100644 index 00000000..a438dcc1 --- /dev/null +++ b/.codex/templates/ai-state/archive.md @@ -0,0 +1,3 @@ +# archive + + diff --git a/.codex/templates/ai-state/conventions.md b/.codex/templates/ai-state/conventions.md new file mode 100644 index 00000000..4cc7188e --- /dev/null +++ b/.codex/templates/ai-state/conventions.md @@ -0,0 +1,8 @@ +# Conventions + +## 语言: {TypeScript/Python/Rust/Go} +## 框架: {Next.js/FastAPI/Actix/...} +## 测试: {Jest/Pytest/Cargo test/...} +## 代码风格: {ESLint配置/Ruff配置/...} +## 命名规范: {camelCase/snake_case/...} +## Git 分支策略: {trunk-based/gitflow/...} diff --git a/.codex/templates/ai-state/design.md b/.codex/templates/ai-state/design.md new file mode 100644 index 00000000..f640712c --- /dev/null +++ b/.codex/templates/ai-state/design.md @@ -0,0 +1,3 @@ +# design + + diff --git a/.codex/templates/ai-state/doing.md b/.codex/templates/ai-state/doing.md new file mode 100644 index 00000000..9ff51e08 --- /dev/null +++ b/.codex/templates/ai-state/doing.md @@ -0,0 +1,7 @@ +# Doing (看板) +## TODO +- {待做任务} +## DOING +- 🔄 {进行中任务} +## DONE +- ✅ {已完成任务} diff --git a/.codex/templates/ai-state/knowledge.md b/.codex/templates/ai-state/knowledge.md new file mode 100644 index 00000000..851ed71f --- /dev/null +++ b/.codex/templates/ai-state/knowledge.md @@ -0,0 +1,6 @@ +# Knowledge + + +## 项目模式 +## 已知陷阱 +## 技术决策记录 diff --git a/.codex/templates/ai-state/lessons.md b/.codex/templates/ai-state/lessons.md new file mode 100644 index 00000000..a07df0a8 --- /dev/null +++ b/.codex/templates/ai-state/lessons.md @@ -0,0 +1,4 @@ +# Lessons + + + diff --git a/.codex/templates/ai-state/plan.md b/.codex/templates/ai-state/plan.md new file mode 100644 index 00000000..869a06ea --- /dev/null +++ b/.codex/templates/ai-state/plan.md @@ -0,0 +1,9 @@ +# Plan + +## 需求: {一句话} +## 预估: {时间} +## 任务列表 +- [ ] 任务1: {描述} — {预估} — {子代理: builder/手动} +- [ ] 任务2: {描述} — {预估} — {依赖: 任务1} +## 技术决策 +- {决策1}: {原因} diff --git a/.codex/templates/ai-state/review.md b/.codex/templates/ai-state/review.md new file mode 100644 index 00000000..1ffdf52f --- /dev/null +++ b/.codex/templates/ai-state/review.md @@ -0,0 +1,3 @@ +# review + + diff --git a/.codex/templates/ai-state/session.md b/.codex/templates/ai-state/session.md new file mode 100644 index 00000000..be53b332 --- /dev/null +++ b/.codex/templates/ai-state/session.md @@ -0,0 +1,7 @@ +# Session + +## 项目: {项目名} +## 当前阶段: {R₀/R/D/P/E/T/V} +## Path: {A/B/C/D} +## 需求摘要: {一句话} +## 更新时间: {时间戳} diff --git a/.codex/templates/ai-state/verified.md b/.codex/templates/ai-state/verified.md new file mode 100644 index 00000000..d26f1ceb --- /dev/null +++ b/.codex/templates/ai-state/verified.md @@ -0,0 +1,3 @@ +# verified + + diff --git a/.codex/workflows/pace.md b/.codex/workflows/pace.md new file mode 100644 index 00000000..1f7d5e82 --- /dev/null +++ b/.codex/workflows/pace.md @@ -0,0 +1,41 @@ +# P.A.C.E. 复杂度路由 (v9.1.0) + +## 评估维度 +- 文件数 (1 / 2-10 / 10-50 / 50+) +- 预估时间 (<30min / 6-12h / 1-3天 / 1周+) +- 架构影响 (无 / 局部 / 跨模块 / 全局) + +## Path A — 快速修复 (≤30min, 1-2 文件) +加载: AGENTS.md (~130L) +阶段: R(轻) → E → T(轻) → V +自动 Skills: [R] context7 | [E] tdd(L1) | [T] verification | [V] kaizen +检查点: cunzhi [DELIVERY_CONFIRMED] + +## Path B — 计划开发 (6-12h, 2-10 文件) +加载: + workflows + 6 skills (~540L) +阶段与自动 Skills: + R₀b: **brainstorm** → spec + design.md → cunzhi [DESIGN_DIRECTION] + R: augment-context/deepwiki → **context7** → 更新 design.md + D: **context7** 查 API → design.md 终稿 → cunzhi [DESIGN_READY] + P: **plan-first** + /plan 原生 → plan.md → cunzhi [PLAN_CONFIRMED] + E: **tdd**(L2, 强制 RED→GREEN) → doing.md 看板 + T: **verification** + **code-review** + /review 原生 → verified.md + V: Kaizen 复盘 → cunzhi [DELIVERY_CONFIRMED] + +## Path C — 系统开发 (1-3 天, 10-50 文件) +加载: + agent-teams + e2e-testing (~700L) +同 Path B + : + E: **agent-teams** 并行 (多代理协作, [agents] 角色) + T: + **e2e-testing** → cunzhi [TESTS_PASSED] + V: 按功能分 commit + **kaizen** + +## Path D — 企业级 (1周+, 50+ 文件) +同 Path C + : + T: + security-review → cunzhi [SECURITY_PASSED] + V: 分 PR 交付, 每个 PR 独立审查 + **kaizen** + Profile: `codex --profile review` 用于最终审查 + +## 路径选择规则 +1. 默认 Path A, 除非满足升级条件 +2. 用户明确说 "简单修一下" → 不要升级到 B +3. 不确定 → 问用户确认复杂度 diff --git a/.codex/workflows/riper-7.md b/.codex/workflows/riper-7.md new file mode 100644 index 00000000..5165bf18 --- /dev/null +++ b/.codex/workflows/riper-7.md @@ -0,0 +1,66 @@ +# RIPER-7 阶段编排 (v9.1.0) + +## 阶段流: R₀ → R → D → P → E → T → V + +### R₀ (预研/头脑风暴, Path B+ 独有) +触发: 用户提交需求且 PACE≥B +**自动加载**: brainstorm skill +工具: augment-context + cunzhi +输入: 用户需求 +输出: .ai_state/design.md (含 spec 需求模板 + 方案草案) +检查点: cunzhi [DESIGN_DIRECTION] + +### R (研究) +触发: R₀ 确认后 或 Path A 直接进入 +**自动加载**: context7 skill +工具: augment-context + deepwiki + web search +输入: design.md 或 用户需求 +输出: 更新 design.md (技术细节) + +### D (设计, Path B+ 独有) +触发: R 完成 +**自动加载**: context7 skill +输入: design.md +输出: design.md 终稿 +检查点: cunzhi [DESIGN_READY] + +### P (规划, Path B+ 独有) +触发: D 确认后 +**自动加载**: plan-first skill + /plan 原生规划 +输入: design.md +输出: .ai_state/plan.md +检查点: cunzhi [PLAN_CONFIRMED] + +### E (执行) +触发: P 确认后 或 Path A R 完成 +**自动加载**: tdd skill (强制模式) + agent-teams (Path C+) +铁律: **先写测试, 再写实现** +过程: + - Path A: 直接开发, 功能验证 + - Path B: tdd L2 (RED→GREEN→REFACTOR), doing.md 看板 + - Path C/D: agent-teams 多代理并行 +输出: .ai_state/doing.md, 代码变更 + +### T (测试/验证) +触发: E 完成 +**自动加载**: verification + code-review skills +工具: /review 原生代码审查 +过程: + - Path A: 功能验证 + lint + - Path B: verification + code-review → verified.md + - Path C/D: + e2e-testing + security-review +输出: .ai_state/verified.md +检查点: cunzhi [TESTS_PASSED] + +### V (验收/交付) +触发: T 通过 +过程: + 1. 验证: plan 无未完成项 + 测试通过 + 2. cunzhi [DELIVERY_CONFIRMED] 用户确认 + 3. **Kaizen 复盘** (必须): + a. git diff --stat 分析变更范围 + b. 提炼经验 → .ai_state/knowledge.md + c. 记录陷阱 → .ai_state/lessons.md + d. 更新 conventions.md (如有新规范) + 4. 归档 → .ai_state/archive.md +输出: 交付完成 + 经验沉淀 diff --git a/.gitignore b/.gitignore index fdd159a9..0d848c6c 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,6 @@ package-lock.json yarn.lock .VSCodeCounter + +# VibeCoding state +.ai_state/