# VibeCoding Ace

**Repository Path**: jichenstudy/VibeCoding-Ace

## Basic Information

- **Project Name**: VibeCoding Ace
- **Description**: VibeCoding Ace 是一个适配 Claude 与 Codex 的 AI 编码工作流框架，内置 PACE 路由器按任务复杂度自动编排开发流程；集成 TDD、强制审查与生命周期 Hook，让 AI 编码更工程化、标准化与可追溯。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VibeCoding Ace

VibeCoding Ace 是一个适配 Claude 与 Codex 的 AI 编码工作流框架，内置 PACE 路由器按任务复杂度自动编排开发流程；集成 TDD、强制审查与生命周期 Hook，让 AI 编码更工程化、标准化与可追溯。

## 核心能力

- **工程化** — TDD、强制审查、生命周期 Hook 内建其中，不是事后补
- **标准化** — PACE 路由器按复杂度自动匹配开发路径，不再凭感觉决定流程
- **可追溯** — 所有决策与状态落入 `.ai_state/`，做了什么、为什么做，都有记录

```mermaid
flowchart LR
    A["需求"] --> B["PACE 路由器"]
    B --> C["任务类型详情"]

    subgraph C["编排开发流程"]
        direction LR
        C1["Hotfix"] ~~~ C2["Bugfix"]
        C3["Quick Feature"] ~~~ C4["Refactor"]
        C5["System"] ~~~ C6["Testing"]
    end

    C --> D["Claude Code"]
    C --> E["OpenAI Codex"]
    D --> F[".ai_state/共享状态"]
    E --> F
```

**9 条铁律**：

| # | 铁律 | 含义 |
|---|------|------|
| 1 | **设计先行** | 未确认不写代码 (Hotfix/Bugfix 例外) |
| 2 | **TDD 强制** | 先测试后实现 |
| 3 | **Sisyphus** | tasks 全完成才进审查 |
| 4 | **Review 强制** | Feature+ 至少一次交叉审查 |
| 5 | **文档即真相** | 阶段转换前 .ai_state/ 必须同步 |
| 6 | **完成度证据** | 报告"完成"必须附 tool_use ID 或输出片段 |
| 7 | **出处优先** | 技术结论必须引用官方文档或源码 URL |
| 8 | **索引先行** | 做决策前先读 `_index.md`，禁止 glob 全目录 |
| 9 | **Hook 是进化器** | Stop 时反思并写 `proposals.md` |

**工程原则**：SRP · OCP · LSP · ISP · DIP · DRY · KISS · 第一性原理 · 先 Why 后 How

## 快速开始

### 前置条件

- 已安装 [Claude Code](https://code.claude.com/docs) ≥ v2.1.121（推荐 ≥ v2.1.139 解锁 /goal /background）
- （可选）[OpenAI Codex](https://github.com/openai/codex) 用于跨模型审查
- （推荐）[claude-mem](https://github.com/thedotmack/claude-mem) 用于跨会话记忆

### 三步启用

```
1. 获取框架文件（二选一）
   ├─ git clone 框架仓库
   └─ 手动复制 .claude/ .codex/ 到项目根目录
          │
          ▼
2. /ace-setup（仅首次，全局安装）
   检查版本 → 装插件 → 配置 Codex → 部署 Hooks
          │
          ▼
3. /ace-init（每个项目一次）
   创建 .ai_state/ → 扫描技术栈 → 生成 init.sh
          │
          ▼
   /ace-dev <需求描述>    ← 开始开发
   /ace-status            ← 随时查看状态
```

## 命令速查

| 命令 | 用途 |
|------|------|
| `/ace-setup` | 全局安装（首次使用） |
| `/ace-init` | 项目初始化（每项目一次） |
| `/ace-dev <需求>` | 开始/继续开发，自动路由 PACE 路径 |
| `/ace-status` | 查看当前 PACE 状态、任务进度、引擎健康 |
| `/ace-review [焦点]` | 单独运行质量审查 |
| `/ace-migrate` | v1.0.0 → v1.1 状态文件迁移 |
| `/ace-preferences <子命令>` | 偏好管理（allow/deny/tool/set-engine） |
| `/compound` | 经验沉淀（Sprint 结束后） |

## 目录结构

```
项目根目录
├── .claude/          ← CC 引擎配置
│   ├── CLAUDE.md     ← 角色指令（宪法）
│   ├── hooks/*.cjs   ← 生命周期自动化 (10 个)
│   ├── skills/*/     ← 命令入口 (8 个)
│   └── agents/*.md   ← 子任务委派 (2 个)
├── .codex/           ← Codex 引擎配置
│   ├── AGENTS.md     ← 角色指令（宪法）
│   ├── hooks/*.py    ← 生命周期自动化 (6 个)
│   ├── prompts/*.md  ← 命令入口 (7 个)
│   ├── agents/*.toml ← 子任务委派 (3 个)
│   └── config.toml   ← 模型/沙箱/Hook 注册
└── .ai_state/        ← 共享状态（运行时自动生成，.gitignore 中不提交）
    ├── _index.md     ← 单一入口
    └── details/      ← 设计/任务/进度/经验/审查
```

- [开发指南](docs/DEVELOPMENT_GUIDE.md) — PACE 路径体系、完整开发流程、状态管理、Hook 系统、双引擎架构
- [维护手册](docs/MAINTENANCE_GUIDE.md) — 日常运维、故障排查、组件维护（新增/修改 Skill/Hook/Agent）