Claude Autonomous Engineer
让 Claude Code 真正实现自主工程 - 纯 Rust 实现，单一二进制
这是一个完整的 Claude Code 自主工程系统，将所有 hooks 和 agents 打包进单一的 Rust 二进制文件（~8MB，包含 5 种语言的 tree-sitter 支持）。通过智能的上下文注入、自动进度同步和代码审查，让 Claude 能够真正自主地完成复杂的工程任务。
🎯 这个工具解决什么问题？
传统 Claude Code 的痛点
你: "帮我实现用户认证系统"
Claude: [写了一些代码]
Claude: "完成了！"
你: "还有很多功能没做啊..."
Claude: "抱歉，我忘记了之前的计划" ❌
使用 Claude Autonomous Engineer
你: "帮我实现用户认证系统"
[系统自动注入上下文]
Claude: "我会先设计架构并生成任务列表..."
[生成 ROADMAP.md - 20个任务]
[生成 API 契约]
Claude: "现在开始 TASK-001: 实现用户注册..."
[写代码 → 写测试 → 自动审查 → 提交]
✓ TASK-001 完成
Claude: "继续 TASK-002: 实现登录功能..."
[自动继续下一个任务]
✓ TASK-002 完成
... [持续执行，直到所有任务完成] ✓
✨ 核心特性
🧠 智能上下文注入
每次交互前自动注入：
- 当前状态 (memory.json) - 正在做什么任务，当前进度
- 任务清单 (ROADMAP.md) - 还有哪些待完成
- API 契约 (api_contract.yaml) - 函数签名和接口规范
- 错误历史 (error_history.json) - 避免重复失败
- 活跃文件 - 正在编辑的代码
🔄 自动进度同步
修改 Markdown 文件时自动更新状态：
你修改: ROADMAP.md
- [x] TASK-001: 用户注册 ← 标记为完成
系统自动: memory.json 更新
{
"current_task": "TASK-002",
"progress": { "tasks_completed": 1 }
}
🛡️ Git Commit 前自动审查
Codex 路径智能解析：系统会自动在以下位置查找 codex 命令：
- 环境变量
CLAUDE_AUTONOMOUS_CODEX_BIN（最高优先级） - 系统 PATH
- nvm 目录
~/.nvm/versions/node/*/bin/codex（自动选择最新版本） - 项目本地
./node_modules/.bin/codex
🔁 自主循环控制
Claude: "这个任务完成了"
[loop_driver hook 自动检查]
→ ROADMAP 还有 pending 任务吗？
- 有 → "继续下一个任务"
- 没有 → "所有任务完成！"
🗺️ 多语言代码骨架提取 (Repository Map)
使用 Tree-sitter 提取代码结构，显著减少 token 消耗：
支持语言：Rust, Python, Go, TypeScript, JavaScript
提取内容：函数签名、类定义、接口、类型等
示例输出 (TOON 格式):
path: example.py
symbols[3]:
Struct,User,"class User:"
Function,__init__,"def __init__(self, name: str):"
Function,greet,"async def greet(self) -> str:"
优势：
✅ 节省 30-60% tokens
✅ BLAKE3 缓存 - 只解析修改的文件
✅ 并行处理 - Rayon 多线程加速
✅ 降低"接口幻觉"风险
📝 最近改进 (v1.0.14)
✨ 新增特性
智能 Codex 路径解析
不再依赖环境变量！系统现在会自动在多个位置智能搜索 codex 命令：
- 🔍 4 级搜索策略：环境变量 → 系统 PATH → nvm 目录 → 项目本地
- 🚀 nvm 支持：自动扫描
~/.nvm/versions/node/*/bin/codex，选择最新版本 - 📦 项目本地支持：自动查找
./node_modules/.bin/codex（向上 5 层） - ⚡ 会话级缓存：首次查找后缓存结果，后续调用 <1μs
- 🎯 精准验证：检查文件存在性、可执行权限、运行
--version验证 - 💡 详细错误提示：找不到 codex 时显示所有搜索位置和安装建议
技术实现：
- 新增
src/hooks/codex_resolver.rs模块（~300 行） - 使用
std::sync::OnceLock实现线程安全缓存 - 遵循项目现有的多策略路径查找模式
- 零新增依赖 - 使用已有的
anyhow、dirs、std::process
用户体验提升：
- ✅ nvm 用户无需配置 - 自动找到 codex
- ✅ 项目本地安装自动识别
- ✅ 环境变量仍可作为最高优先级覆盖
- ✅ 清晰的错误信息指导安装
Repository Map 多语言支持
新增对 Python、Go、TypeScript/TSX、JavaScript/JSX 的完整支持！
现在 claude-autonomous map 命令可以提取以下语言的代码骨架：
- 🦀 Rust - 完整支持（原有功能）
- 🐍 Python - 类、函数、装饰器 (@staticmethod, @property)、async/await
- 🐹 Go - 函数、方法(receiver)、结构体、接口、类型别名
- 📘 TypeScript/TSX - 函数、类、接口、类型、React 组件、泛型
- 📙 JavaScript/JSX - 函数、类、箭头函数、React 组件
技术实现：
- 使用 Tree-sitter 进行语言无关的 AST 解析
- 每种语言约 300 行代码实现
- Trait-based 架构，易于扩展新语言
- 共享缓存、格式化、输出逻辑
测试验证：在 /tmp/multi-lang-test 中测试了所有语言，成功提取 20 个符号！
Bug 修复
修复 loop_driver 误判空 ROADMAP 为"已完成"的问题
在之前的版本中，当 ROADMAP 存在但为空（total=0，即还未生成任务）时，loop_driver hook 会误判为"所有任务已完成"，导致在规划阶段就触发 Stop 事件，阻止继续工作。
修复内容：
- 新增检查：ROADMAP 为空时返回 "ROADMAP EMPTY" 错误，提示需要先生成任务
- 调整判断顺序：先检查
total == 0，再检查complete - 确保只有在真正完成所有任务时才允许停止
影响：
- 修复前：空 ROADMAP → "✓ 所有任务完成" → 意外停止
- 修复后：空 ROADMAP → "❌ ROADMAP 为空，请生成任务" → 正确提示
这个修复确保了 project-architect-supervisor 能够正常完成任务规划阶段，不会被提前中断。
📦 安装
方式 1: Cargo Install（推荐）
方式 2: DEB 包（Debian/Ubuntu）
方式 3: RPM 包（Fedora/RHEL/CentOS）
验证安装
# claude-autonomous 1.0.13
🚀 快速开始
第一步：初始化项目
在你的项目根目录运行：
这会创建完整的目录结构：
my-project/
└── .claude/
├── settings.json # Hook 配置
├── agents/ # 5 个 agent 定义
│ ├── project-architect-supervisor.md
│ ├── code-executor.md
│ ├── codex-reviewer.md
│ ├── prd-generator.md
│ └── visual-designer.md
├── status/ # 状态管理（唯一真相来源）
│ ├── memory.json # 当前状态
│ ├── ROADMAP.md # 任务清单（需手动创建或让 Claude 生成）
│ ├── api_contract.yaml # API 契约
│ ├── error_history.json # 错误历史
│ └── decisions.log # 决策日志
└── phases/ # 阶段详细计划
第二步：在 Claude Code 中开始工作
现在打开 Claude Code 并开始一个复杂任务：
你: "帮我实现一个完整的用户认证系统，包括注册、登录、密码重置、
JWT token 管理、权限控制"
Claude 会：
-
设计架构（通过 project-architect-supervisor agent）
- 生成
ROADMAP.md- 包含 15-20 个详细任务 - 生成
api_contract.yaml- 定义所有函数签名 - 生成阶段计划和任务规格
- 生成
-
开始执行（通过 code-executor agent）
- TASK-001: 实现用户模型
- TASK-002: 实现注册 API
- TASK-003: 添加密码加密
- ... (自动继续)
-
自动审查（通过 codex-reviewer agent）
- 每次 git commit 前自动触发
- 检查代码质量、测试覆盖、API 契约一致性
-
持续执行直到完成
- loop_driver 检查 ROADMAP
- 还有 pending 任务 → 继续
- 所有完成 → 停止并报告
第三步：查看进度
随时查看当前状态：
输出：
╔══════════════════════════════════════════════════════════════════╗
║ Claude Autonomous Engineering Status ║
╚══════════════════════════════════════════════════════════════════╝
📁 Project Root: /home/user/my-project
🧠 Current State:
Project: My Awesome Project
Task: TASK-005
Status: in_progress
Retries: 0/5
📋 Progress:
✓ Completed: 4
▶ In Progress: 1
○ Pending: 10
! Blocked: 0
Total: 15 (26.7%)
📍 Current Phase: Phase 1 - Core Authentication
第四步（可选）：生成 Repository Map（代码骨架）
Repository Map 会用 Tree-sitter 提取代码结构骨架（函数/结构体/impl 等），在上下文注入时显著减少 token 消耗，并降低"接口幻觉"风险。
支持的编程语言：
- 🦀 Rust (.rs) - Function, Struct, Enum, Trait, Impl
- 🐍 Python (.py) - Function, Class, Method, 装饰器, async/await
- 🐹 Go (.go) - Function, Method, Struct, Interface, Type Alias
- 📘 TypeScript (.ts, .tsx) - Function, Class, Interface, Type, Method
- 📙 JavaScript (.js, .jsx) - Function, Class, Method, React 组件
# 默认输出（推荐）：.claude/repo_map/structure.toon
# 输出 Markdown（更适合人读，但更长）
# 指定输出路径
特性：
- ✅ 自动识别文件语言并选择对应的 extractor
- ✅ BLAKE3 哈希缓存 - 只重新解析修改过的文件
- ✅ TOON 格式 - 节省 30-60% tokens
- ✅ 并行处理 - 使用 Rayon 多线程加速
说明：
inject_state会优先读取.claude/repo_map/structure.toon，不存在时再读取.claude/repo_map/structure.md。.claude/repo_map/默认已加入.gitignore（建议不要提交生成物）。
第五步（可选）：Git 状态机（state）
状态机用于把“长周期开发阶段”显式化（planning/coding/testing/reviewing/completed/blocked），并提供历史查询与回滚。
# 查看当前状态
# 手动创建一次状态转换（会写入 .claude/status/state.json，并创建一条 git commit + tag）
# 列出/可视化状态历史
# 回滚到某个历史 tag（仅回滚 .claude/status/state.json）
注意：
- 状态机是“显式启用”：只有当
.claude/status/state.json存在时，inject_state才会注入状态机上下文，loop_driver才会尝试自动状态转换。 - 为避免污染用户提交，状态转换会在 index 存在 staged changes 时拒绝执行（请先 commit/unstage）。
📚 实际使用场景
场景 1: 从零开始构建新功能
# 在 Claude Code 中
场景 2: 重构现有代码
场景 3: 修复 Bug 和添加测试
🔧 命令参考
初始化命令
| 命令 | 说明 | 示例 |
|---|---|---|
init |
初始化项目 | claude-autonomous init |
init --name <name> |
指定项目名称 | claude-autonomous init --name "My API" |
init --force |
强制覆盖已有配置 | claude-autonomous init --force |
查看命令
| 命令 | 说明 | 输出 |
|---|---|---|
status |
显示项目状态和进度 | 当前任务、完成度、阻塞项 |
agents |
列出所有嵌入的 agents | 5 个 agent 名称列表 |
root |
显示项目根目录路径 | /path/to/project |
doctor |
诊断环境和配置 | 检查文件完整性、配置正确性 |
Hook 命令（通常由 Claude Code 自动调用）
| 命令 | 触发时机 | 作用 |
|---|---|---|
hook claude_protocol |
SessionStart | 注入 CLAUDE.md 静态规范（自主工程协议） |
hook inject_state |
UserPromptSubmit | 注入上下文到 Claude |
hook progress_sync |
PostToolUse (Write/Edit) | 同步 Markdown 进度到 memory.json |
hook codex_review_gate |
PreToolUse (Bash - git commit) | Git commit 前审查代码 |
hook error_tracker |
PostToolUse (Bash) | 记录失败命令到 error_history.json，并递增 retry_count |
hook loop_driver |
Stop | 检查是否还有任务，决定是否继续 |
注意：Claude Code 会校验 hook 命令 stdout 的 JSON schema。
对于只做“副作用”的 hook（如progress_sync/error_tracker），建议返回最小 no-op 结构，避免出现Hook JSON output validation failed：{"hookSpecificOutput":{"for PostToolUse":{"hookEventName":"PostToolUse"}}}
🏗️ 系统架构
Hook 集成流程
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code Session │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Session Start → [claude_protocol] → 注入 CLAUDE.md 静态规范 │
│ ↓ │
│ 注入 Autonomous Engineering Protocol: │
│ • Prime Directives (优先级规则) │
│ • Agent Swarm Protocol (Agent 协调) │
│ • The Loop (自主循环流程) │
│ • Anti-Patterns (禁止行为) │
│ │
│ User Prompt → [inject_state] → Claude (with full context) │
│ ↓ │
│ 读取并注入: │
│ • memory.json │
│ • ROADMAP.md (pending 任务) │
│ • TASK-xxx.md (当前任务规格) │
│ • api_contract.yaml │
│ • error_history.json │
│ │
│ Claude 输出 → [progress_sync] → 自动更新 memory.json │
│ ↓ │
│ 监听文件修改: │
│ • ROADMAP.md → 同步进度 │
│ • TASK-xxx.md → 同步当前任务 │
│ │
│ Bash 命令执行 → [error_tracker] → 记录失败命令 │
│ ↓ │
│ 失败时自动: │
│ • 记录到 error_history.json │
│ • 递增 retry_count │
│ • 供 Claude 参考避免重复 │
│ │
│ git commit → [codex_review_gate] → 审查 → PASS/FAIL │
│ ↓ │
│ 自动审查: │
│ • API 契约一致性 │
│ • 测试覆盖 │
│ • 代码质量 │
│ │
│ Stop → [loop_driver] → 检查 ROADMAP → CONTINUE/DONE │
│ ↓ │
│ 检查是否还有: │
│ • [ ] pending 任务 → 阻止停止 │
│ • 全部 [x] → 允许停止 │
│ │
└─────────────────────────────────────────────────────────────────┘
核心组件
| 组件 | 语言 | 大小 | 作用 |
|---|---|---|---|
| CLI 主程序 | Rust | 2MB | 命令行入口、Hook 执行 |
| State Manager | Rust | - | 解析 ROADMAP、memory.json |
| Context Manager | Rust | - | 智能上下文管理（token 预算控制） |
| Repository Mapper | Rust | - | 多语言代码骨架提取（Tree-sitter） |
| Project Finder | Rust | - | Git-like 根目录查找（支持 submodule） |
| Templates | Embedded | - | 5 个 agents + CLAUDE.md 模板 |
为什么选择 Rust？
| 特性 | 说明 |
|---|---|
| 极速启动 | < 50ms - 几乎零感知延迟 |
| 超小体积 | 2MB 单文件 - 所有功能全包含 |
| 零依赖 | 无需任何运行时或库 |
| 低内存 | < 20MB - 轻量高效 |
| 一键部署 | 单一二进制，复制即用 |
| 高性能 | Hook 执行 < 30ms - 极致优化 |
🔍 智能根目录检测
CLI 支持复杂的项目结构，包括 git submodule：
my-project/ ← 主项目
├── .claude/ ← 配置在这里
├── backend/
│ └── api/
└── submodules/
└── shared-lib/ ← git submodule
└── deep/path/
无论你在哪里执行命令，都能找到正确的 .claude 目录：
# 在主项目
# → /home/user/my-project
# 在 submodule 深层目录
# → /home/user/my-project (正确找到父项目！)
查找顺序：
- Git superproject（优先 - 处理 submodule）
- Git 仓库根目录
- 当前目录
- 向上遍历父目录
📋 settings.json 配置
初始化后生成的 settings.json 非常简洁：
对比之前复杂的 bash 脚本（100+ 字符），现在只需要简单的命令调用。
🎓 内置 Agents
1. project-architect-supervisor
职责: 架构设计和任务规划 输出:
ROADMAP.md- 完整任务列表api_contract.yaml- API 契约PHASE_PLAN.md- 阶段计划TASK-xxx.md- 任务规格
触发词: "设计架构"、"规划项目"、"生成任务列表"
2. code-executor
职责: TDD 方式实现代码 工作流:
- 读取
TASK-xxx.md需求 - 读取
api_contract.yaml签名 - 写测试 → 验证失败 → 实现代码 → 验证通过
- Lint 检查
- Git commit（触发自动审查）
触发词: "实现"、"写代码"、"开发功能"
3. codex-reviewer
职责: 代码审查（Git commit 前自动触发） 检查项:
- API 契约一致性
- 测试覆盖率
- 代码质量（Lint、格式）
- 安全问题
输出: PASS（允许提交）或 FAIL（阻止 + 反馈问题）
4. prd-generator
职责: 从需求生成 PRD 文档 触发词: "写 PRD"、"需求文档"
5. visual-designer
职责: UI/UX 设计建议 触发词: "设计界面"、"UI 设计"
❓ 常见问题
Q: 如何配置 codex 命令路径？
A: 系统会自动智能查找 codex，无需手动配置！
自动查找顺序：
- 环境变量
CLAUDE_AUTONOMOUS_CODEX_BIN（最高优先级） - 系统 PATH - 直接执行
codex --version - nvm 目录 -
~/.nvm/versions/node/*/bin/codex（自动选择最新版本） - 项目本地 -
./node_modules/.bin/codex（向上查找 5 层）
手动配置（可选）：
# 设置环境变量指定 codex 路径
# 或添加到 shell 配置文件
错误排查： 如果系统找不到 codex，会显示详细的搜索位置和安装建议：
Codex command not found in any of the following locations:
1. Environment variable: CLAUDE_AUTONOMOUS_CODEX_BIN (not set)
2. System PATH (command 'codex' not found)
3. nvm directories: ~/.nvm/versions/node/*/bin/codex (not found)
4. Project-local: ./node_modules/.bin/codex (not found)
💡 Installation suggestions:
- Install via npm: npm install -g @anthropic-ai/codex
- Or set CLAUDE_AUTONOMOUS_CODEX_BIN to the full path
- Detected nvm at: ~/.nvm
Try: nvm use <version> && npm install -g @anthropic-ai/codex
Q: 如何让 Claude 停止自主循环？
A: loop_driver hook 会自动检查 ROADMAP。如果想手动停止：
- -或者删除/注释掉 Stop hook：
// 临时禁用 loop_driver
Q: 任务卡住了怎么办？
A: 系统会自动检测重试次数：
// memory.json
手动干预：
- --Q: 如何自定义 agents？
A: 编辑 .claude/agents/*.md 文件：
# 修改 code-executor 的提示词
Agent 定义使用 Frontmatter + Markdown：
name: my-custom-agent
description: "Custom agent for special tasks"
model: sonnet
color: purple
[你的提示词...]
Q: 能否在多个项目中共享配置？
A: 可以。创建一个模板项目：
# 创建模板
# 自定义 agents 和 settings.json
# 在新项目中复制
Q: 支持哪些编程语言？
A: 系统本身是语言无关的 - agents 可以处理任何语言！
Repository Map (代码骨架提取) 目前支持:
- 🦀 Rust - Function, Struct, Enum, Trait, Impl
- 🐍 Python - Function, Class, Method, 装饰器(@staticmethod 等), async/await
- 🐹 Go - Function, Method (receiver), Struct, Interface, Type Alias
- 📘 TypeScript/TSX - Function, Arrow Function, Class, Interface, Type, 泛型
- 📙 JavaScript/JSX - Function, Arrow Function, Class, React 组件
其他语言 - Agents 可以处理任何语言:
- ✅ Java, C++, C#, PHP, Ruby...
- ✅ Web (React, Vue, Next.js, Angular...)
- ✅ Mobile (Swift, Kotlin, Flutter...)
- ✅ 任何有 TDD 支持的语言
💡 扩展提示: 添加新语言的 Repository Map 支持只需 ~300 行代码。 查看
src/repo_map/languages/了解实现模式,欢迎贡献 PR!
Q: 如何与现有 Git 工作流集成？
A: 完全兼容标准 Git 流程：
# 正常的 Git 操作
# 系统只是在 commit 前添加了审查
要禁用审查（CI/CD 环境）：
# 环境变量禁用
SKIP_REVIEW=1
Q: 性能如何？会不会拖慢 Claude Code？
A: 极快！
| Hook | 执行时间 |
|---|---|
| inject_state | < 50ms |
| progress_sync | < 20ms |
| codex_review_gate | < 30ms (不审查时) |
| loop_driver | < 10ms |
总开销: 每次交互约 50-100ms，几乎感觉不到。
🔧 高级用法
自定义上下文预算
编辑 .claude/settings.json 添加：
错误历史管理
手动添加错误记录（避免重复失败）：
// .claude/status/error_history.json
决策日志
记录重要的架构决策：
// .claude/status/decisions.log
2024-01-01 10:00 [TASK-003] Chose JWT over sessions (stateless, better scaling)
2024-01-01 11:30 [TASK-007] Use bcrypt for passwords (industry standard)
🛠️ 开发和贡献
本地开发
# 开发模式运行
# 运行测试
# 发布构建
项目结构
src/
├── main.rs # CLI 入口
├── lib.rs # 库导出
├── cli/ # 命令行处理
├── hooks/ # 6 个 hook 实现 + codex 路径解析
│ ├── claude_protocol.rs # SessionStart - 注入协议
│ ├── inject_state.rs # UserPromptSubmit - 上下文注入
│ ├── progress_sync.rs # PostToolUse - 进度同步
│ ├── error_tracker.rs # PostToolUse - 错误追踪
│ ├── codex_review_gate.rs # PreToolUse - 代码审查门禁
│ ├── codex_resolver.rs # Codex 路径智能解析（支持 nvm）
│ ├── codex_executor.rs # Codex 命令执行器
│ ├── review_context.rs # 审查上下文构建
│ ├── review_parser.rs # 审查结果解析
│ ├── state_tracker.rs # 状态追踪
│ └── loop_driver.rs # Stop - 循环控制
├── state/ # 状态管理
│ ├── models.rs # Memory, Task 数据结构
│ ├── parser.rs # Markdown/YAML 解析
│ └── sync.rs # 进度同步逻辑
├── context/ # 上下文管理
│ ├── manager.rs # 上下文组装
│ └── truncate.rs # Token 预算控制
├── repo_map/ # Repository Mapping
│ ├── mod.rs # 核心逻辑
│ ├── extractor.rs # 语言提取器 trait
│ ├── parser.rs # Tree-sitter 解析器
│ ├── generator.rs # Markdown 输出
│ ├── generator_toon.rs # TOON 格式输出
│ ├── cache.rs # BLAKE3 缓存
│ └── languages/ # 语言特定提取器
│ ├── rust.rs # Rust 提取器
│ ├── python.rs # Python 提取器
│ ├── go.rs # Go 提取器
│ ├── typescript.rs # TypeScript/TSX 提取器
│ └── javascript.rs # JavaScript/JSX 提取器
├── project/ # 项目管理
│ ├── initializer.rs # init 命令
│ └── root_finder.rs # 根目录查找
├── state_machine/ # Git 状态机
│ ├── git_state.rs # Git 集成
│ └── workflow.rs # 状态转换
├── templates/ # 资源嵌入
│ ├── agents.rs # Agent 模板
│ └── files.rs # 配置模板
└── utils/ # 工具函数
├── git.rs
├── fs.rs
└── json.rs
embedded/ # 嵌入资源
├── agents/ # 5 个 agent 定义
└── templates/ # 模板文件
打包发布
# 构建 DEB 包
# 构建 RPM 包
# 发布到 crates.io
📄 License
MIT License - 详见 LICENSE
🙏 致谢
- Claude Code - Anthropic 的 AI 编程助手
- Rust 社区 - 优秀的工具和生态
- 所有贡献者
🔗 相关链接
开始自主工程之旅！ 🚀
# 然后在 Claude Code 中说: "帮我实现完整的用户系统"