<img src="https://raw.githubusercontent.com/shirayner/ace/main/assets/logo.svg" width="48" align="center"> ACE

🎯 什么是 ACE？

ACE 是一个AI 开发环境配置工具，基于 Claude Code 官方最佳实践构建，融合认知科学、控制论、软件工程等领域的深度理论，为开发者提供：

• 🧠 认知增强规则 — 8 条基于认知科学的深度思考与代码质量原则
• 🤖 专业级 AI Skills — 4 个面向不同开发场景的智能技能
• 🛡️ 安全防护体系 — Shell Hooks 守卫 + Settings Deny 规则双重保障
• 📝 规范驱动工作流 — OpenSpec 集成的需求管理体系
• 🧩 跨会话记忆系统 — 持久化的开发者画像与项目记忆

视频教程

从下载安装到实际使用的完整演示：

动图速度过快，另有示例视频：ACE 使用示例

✨ 一分钟速览

安装

# 一键安装，即刻拥有专业级 AI 开发环境
npm install -g @shirayner/ace

初始化

$ ace init
◇  ace v0.1.6
│
◇  Installed to ~/.claude/
│
│  ◆ Core Config     2 files
│  ◆ Rules           8 files
│  ◆ Plugin          installed
│  ◆ Hooks           1 file
│  ◆ Safety Guards   7 files
│  ◆ Memory          2 files
│
◆  20 installed
│
┌  Next steps
│  Get started
│    1. cd <your-project> && ace spec init
│    2. Open Claude Code, type: /opsx:propose
│
│  Customize
│    Change role      edit ~/.claude/memory/user_profile.md
│    Adjust rules     edit ~/.claude/rules/ace/
│    Safety guards    edit ~/.claude/settings.json (deny rules)
│    Verify setup     ace doctor
└
└  Done. Go to your project and run ace spec init.

Spec Coding 完整流程

进入工作目录

# 进入工作目录
$ mkdir my-project 
$ cd my-project

Spec 初始化

# 执行 aspec 初始化
$ ace spec init
✓ aspec 工作流已初始化
Done! 规范驱动开发已就绪。

Spec驱动开发

# 在 Claude Code 中体验Spec开发流程：
# 输入 /opsx:proposal 命令后，一路交互式澄清、确认，然后需求完成，Spec归档
$ claude

> /opsx:proposal 帮我实现用户积分系统

Claude: 【需求澄清】对需求不确定的地方提出疑问？→  请求人工澄清
人工：选择选项，或者进行纠正，然后点击submit

Claude: 【需求对齐】Claude输出自己对本需求的理解 → 请求人工确认
人工：选择确认，或者纠正信息，然后点击submit

-- 人工确认之后，Cluade会创建提案

Claude: 【技术设计澄清】对技术不确定的地方提出疑问 → 请求人工确认
人工：选择确认，或者纠正信息，然后点击submit

Claude: 【技术设计对齐】Claude输出自己对本需求的技术方案设计的理解 → 请求人工确认
人工：选择确认，或者纠正信息，然后点击submit

-- 人工确认之后，Cluade会创建Design

Claude: 【Design审批并创建Tasks】Claude请求人工确认Design设计，然后创建Tasks → 请求人工审批
人工：选择确认，或者纠正信息，然后点击submit

-- 人工确认之后，Cluade会创建tasks

Claude: 【执行】Claude 请求按规划的任务进行代码实现 → 请求人工审批
人工：选择确认，或者纠正信息，然后点击submit

-- 人工确认之后，Cluade会进行代码实现，然后进行经验收集

Claude: 【归档同步】Claude 会请求进行归档同步→ 请求人工审批
人工：选择确认，或者纠正信息，然后点击submit

-- 人工确认之后，Cluade会对Spec进行归档同步

健康检查

$ ace doctor
✓ CLAUDE.md 配置正常
✓ 8 条规则文件完整
✓ 4 个 Skills 可正常加载
✓ Hooks 安全守卫运行中
✓ 记忆目录可访问
All systems operational.

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────┐
│                        ACE 架构全景                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Rules     │  │   Skills    │  │   Hooks   │         │
│  │  (8 规则)    │  │  (4 技能)    │  │  (Shell守卫) │         │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤         │
│  │ • thinking  │  │ • auto-goal │  │ • bash-     │         │
│  │ • clean-code│  │ • coding    │  │   guard     │         │
│  │ • code-qual │  │ • skill-    │  │ • file-     │         │
│  │ • reporting │  │   creator   │  │   guard     │         │
│  │ • task-rec  │  │ • skill-    │  │ • content-  │         │
│  │ • context-  │  │   optimize  │  │   guard     │         │
│  │   hygiene   │  │             │  │ • java-     │         │
│  │ • memory-   │  │             │  │   compile   │         │
│  │   policy    │  │             │  │             │         │
│  │ • interactive│  │             │  │             │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │    Hooks    │  │   Memory    │  │    Spec     │         │
│  │ (角色脚本)   │  │  (记忆系统)  │  │ (规范驱动)   │         │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤         │
│  │ • Java 编译 │  │ • MEMORY.md │  │ • config    │         │
│  │   检查      │  │ • user_     │  │   .yaml     │         │
│  │ • TypeScript│  │   profile   │  │ • dimensions│         │
│  │   检查      │  │ • roles/    │  │   .md       │         │
│  │ • 更多...   │  │             │  │ • experience│         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🎓 核心设计理念

ACE 的设计融合了多学科的深层洞察：

认知科学

• 双过程理论 (Kahneman) — 简单任务快速响应，复杂任务深度分析
• 认知负荷理论 (Sweller) — 渐进式信息披露，避免工作记忆过载
• 元认知监控 — 持续自我监控与策略调整

控制论

• OODA 循环 (Boyd) — 观察-定向-决策-行动的快速迭代
• 必要多样性定律 (Ashby) — 策略库必须匹配任务复杂度
• 闭环控制 — 每个操作都内建验证

软件工程

• Clean Code 原则 (Robert C. Martin)
• 单一职责 (SOLID)
• 渐进式复杂度 (OpenAI Agent 最佳实践)

📖 详细理论解读请查看 理论基础文档

🚀 快速开始

1. 安装 ACE

npm install -g @shirayner/ace

2. 初始化环境

ace init

按提示选择你的角色和预设。ACE 会自动配置：

• 全局 CLAUDE.md 索引
• 8 条认知规则
• 4 个 AI Skills
• Shell Hooks 安全守卫
• 角色特定脚本和开发者画像

3. 验证安装

ace doctor

4. 开始项目（可选）

# 初始化规范驱动开发工作流
ace spec init ./my-project
cd my-project

# 开始开发
claude

📚 文档导航

新手入门

• 5 分钟快速开始 — 从零到专业开发环境
• 安装指南 — 详细安装与配置
• 第一个项目 — 手把手入门教程

理解 ACE

• 为什么选 ACE — 价值主张与核心优势
• 解决的问题 — ACE 如何应对开发痛点
• 方案对比 — 与其他工具的比较

深度架构

• 架构全景 — 完整组件关系图
• 8 条规则详解 — 每条规则的用途与设计
• 4 个 Skills 详解 — 工作原理与最佳实践
• aspec 规范驱动 — spec coding 完整工作流
• Shell Hooks 安全体系
• Hooks 角色脚本
• 记忆系统
• OpenSpec 集成

理论基础

• 理论总览
• 认知科学基础
• 控制论与系统论
• 哲学基础
• 心理学洞察
• 社会学视角

参考手册

• CLI 完整参考
• 合并策略
• 角色说明

🛡️ 非破坏性设计

ACE 遵循零侵入原则：

• 智能合并 — CLAUDE.md 使用标记区块替换，settings.json 深度合并，用户配置始终保留
• ACE 文件自动覆盖 — rules/ace/、hooks/ 等 ACE 自有文件升级时自动更新，无需用户决策
• 自动备份 — 首次安装前创建完整快照
• 干净卸载 — ace uninstall 一键恢复原始状态
• 命名空间隔离 — 所有文件使用 ace/ 前缀，避免冲突

🤝 贡献

欢迎贡献！我们同时在 GitHub 和 GitLab 维护代码库。

• 报告问题：使用 GitHub Issues
• 提交改进：Fork & Pull Request
• 讨论想法：GitHub Discussions

查看 CONTRIBUTING.md 了解详情。

📄 License

MIT © 2024