# ai-dev-template

**Repository Path**: cn-zhangpeng/ai-dev-template

## Basic Information

- **Project Name**: ai-dev-template
- **Description**: 将 OpenSpec 需求规范与 Harness 编码约束合二为一，让 AI 智能体按标准执行，业务项目开箱即用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harness

**AI 驱动开发规范包** — 将 OpenSpec 需求规范与 Harness 编码约束合二为一，让 AI 智能体按标准执行，业务项目开箱即用。

核心哲学是"人类掌舵，智能体执行"：不追求更强的模型，而是优化模型运行的环境。通过上下文工程（AGENTS.md 活文档 + 按需检索）、架构约束（分层依赖 + 命名规范）、反馈循环（活文档机制 + 自测校验），为后端（Spring Boot 3）、前端（Vue 3）、小程序（uni-app）三端提供统一的开发规范。

## 1. 规范包组成

| 模块 | 职责 | 对应目录 |
|---|---|---|
| **OpenSpec** | 需求提案 → 技术设计 → 行为契约 → 任务拆解 | `openspec/` |
| **Harness** | 编码规范、目录结构、代码模板、安全规则 | `harness/` |
| **通用规范** | Git 规范、测试规范、项目目录结构 | 根目录 `.md` 文件 |

## 2. 技术栈

| 端 | 技术栈 |
|---|---|
| 后端 | Java 17 / Spring Boot 3 / MyBatis-Plus / MySQL / Redis / Knife4j / OpenFeign |
| 前端（普通） | Vue 3 (Composition API) / Vite / Vant 或 Element Plus / Pinia / Vue Router / Axios |
| 前端（后台管理） | Vue 3 (Composition API) / Vite / Element Plus / Pinia / Vue Router / Axios |
| 小程序 | uni-app / Vue 3 / uni-ui / uv-ui / 微信小程序 |

## 3. 目录结构

```
ai-dev-template/
├── AGENTS.md                    # AI 智能体工作流规范（始终读取）
├── CLAUDE.md                    # Claude Code 项目级上下文约束
├── openspec/                    # OpenSpec 规范工作流
│   ├── AGENTS.md                # OpenSpec 工作流与 AI 行为约束
│   ├── config.yaml              # proposal/design/specs/tasks 编制规则
│   ├── project.md               # 项目全局上下文模板（业务项目填空）
│   ├── specs/                   # 已归档规范（source of truth，入 git）
│   └── changes/                 # 进行中的变更提案（入 .gitignore，不入库）
├── harness/common/              # 通用编码规范
│   └── AGENTS.md                # 命名规范、安全规则、活文档机制、AI 行为约束
├── harness/server/              # 后端规范
│   ├── AGENTS.md                # 后端编码规则 + 模板索引
│   └── templates/               # 各层代码模板、公共模块、配置模板
├── harness/portal/              # 普通前端规范
│   ├── AGENTS.md                # 普通前端编码规则 + 模板索引
│   └── templates/               # 入口配置、页面组件模板
├── harness/admin-portal/        # 后台管理前端规范
│   ├── AGENTS.md                # 后台管理编码规则 + 模板索引
│   └── templates/               # 入口配置、页面组件模板
└── harness/applet/              # 小程序规范
    ├── AGENTS.md                # 小程序编码规则 + 模板索引
    └── templates/               # 入口配置、API 封装、页面组件模板
```

---

## 4. 引入方式

将规范包中的以下内容复制到业务项目根目录：

```
openspec/
harness/
AGENTS.md
CLAUDE.md
```

复制完成后，业务项目根目录结构如下：

```
business-project/
├── AGENTS.md
├── CLAUDE.md
├── openspec/
│   ├── AGENTS.md
│   ├── config.yaml
│   ├── project.md
│   ├── specs/
│   └── changes/
└── harness/
    ├── common/
    ├── server/
    ├── portal/
    ├── admin-portal/
    ├── applet/
    ├── project-layout.md
    ├── git-rules.md
    ├── test-rules.md
    └── VERSION
```

---

## 5. 新项目初始化

规范包复制到业务项目后，所有初始化工作由 AI 按规范自动完成，无需手动执行命令或脚本。

### 5.1 向 AI 发送初始化指令

将以下提示词中的变量填写为实际值，发送给 AI：

```text
请基于当前项目中的规范包（openspec/ + harness/ + AGENTS.md + CLAUDE.md），帮我初始化新项目。

项目信息：
- 组织英文名（org）：acme
- 组织英文名首字母大写（Org）：Acme
- 项目英文名（project）：trade
- 项目英文名首字母大写（Project）：Trade
- 数据库名（database）：trade
- 项目中文名：交易管理系统
- 需要初始化的端：后端 + 后台管理前端（按需选择，可多选）

请严格按以下步骤执行：

1. 读取 openspec/project.md，填写项目全局上下文（项目中文名、版本、所属团队等）
2. 替换所有模板变量（{org}/{Org}/{project}/{Project}/{database}），范围包括：
   - openspec/project.md
   - harness/server/templates/*.md
   - harness/portal/templates/*.md
   - harness/admin-portal/templates/*.md
   - harness/applet/templates/*.md
   - harness/project-layout.md
3. 按 harness/project-layout.md 创建对应端的项目目录结构
4. 按 harness/{端}/templates/ 生成初始代码骨架（启动类、公共模块、配置类、入口文件等）
5. 配置基础环境（application.yml、pom.xml、vite.config.js、package.json 等）
6. 验证项目可正常编译/运行
```

### 5.2 模板变量说明

AI 会自动识别并替换以下变量：

| 变量 | 说明 | 示例 |
|---|---|---|
| `{org}` | 组织/团队英文名（小写） | `acme` |
| `{Org}` | 组织/团队英文名（首字母大写） | `Acme` |
| `{project}` | 项目英文名（小写） | `trade` |
| `{Project}` | 项目英文名（首字母大写） | `Trade` |
| `{database}` | 数据库名 | `trade` |

### 5.4 第四步：填写项目上下文

打开 `openspec/project.md`，填写项目基本信息：
- 项目中文名
- 版本号
- 其他自定义上下文

---

## 6. AI 开发工作流

规范包引入后，人类只需描述需求，AI 自动读取规范并执行。具体工作流（Propose → Define → Apply → Archive）已定义在 `openspec/AGENTS.md` 中，无需在提示词里重复。

### 6.1 人类提需求

直接向 AI 描述功能需求即可，例如：

```text
我要实现一个订单管理模块：
- 支持订单的增删改查
- 订单状态流转：待付款 → 已付款 → 已发货 → 已完成
- 需要分页列表、详情查看、状态变更接口
- 涉及数据库表：订单主表、订单明细表

请按 openspec/ 和 harness/ 下的规范执行开发。
```

### 6.2 AI 自动执行

AI 收到指令后会自动：

1. 读取 `openspec/AGENTS.md` 了解 OpenSpec 四阶段工作流
2. 读取 `openspec/config.yaml` 了解文档编制规则
3. 读取 `openspec/project.md` 了解项目上下文
4. 读取 `harness/common/AGENTS.md` 了解通用编码规范
5. 读取对应端的 `harness/{端}/AGENTS.md` 了解技术栈与代码模板
6. 在 `openspec/changes/` 下创建变更目录，编写 proposal/design/tasks
7. 确认无歧义后，按 checklist 逐个实现代码
8. 自测通过，更新 tasks.md 状态
9. 归档到 `openspec/specs/`，清理工作区

人类只需在 **proposal 阶段确认需求范围** 和 **Apply 阶段验收代码** 两个节点介入，其余由 AI 按规范自动完成。

---

## 7. 老项目接入

已有项目接入规范包，不必一次性全部重写，建议分阶段对齐：

| 阶段 | 动作 | 优先级 |
|---|---|---|
| **P0** | 引入规范包文件（openspec/、harness/、根目录规范） | 高 |
| **P0** | 补充 `openspec/project.md` 项目上下文 | 高 |
| **P1** | 按 `harness/project-layout.md` 检查并调整目录结构 | 中 |
| **P1** | 按 `harness/common/AGENTS.md` 统一命名规范 | 中 |
| **P2** | 按各端 `AGENTS.md` 对齐技术栈与代码风格 | 低 |
| **P2** | 补充公共模块（ResultUtil、异常处理、拦截器等） | 低 |
| **P3** | 启用 OpenSpec 工作流管理后续需求 | 低 |

---

## 8. 规范包升级

### 8.1 升级前检查

```bash
# 查看当前引用的规范包版本
cat harness/VERSION

# 查看规范包远程更新
git fetch ai-dev-template-remote
```

### 8.2 合并更新

**手动复制方式**：
```bash
# 下载新版规范包，对比 diff 后选择性合并
diff -r old-harness/openspec new-harness/openspec
diff -r old-harness/harness new-harness/harness
```

**Git Subtree 方式**：
```bash
git subtree pull --prefix=openspec git@github.com:your-org/ai-dev-template.git main --squash
git subtree pull --prefix=harness git@github.com:your-org/ai-dev-template.git main --squash
# 根目录文件需手动对比合并
```

### 8.3 处理冲突原则

- **通用规范（harness/common/AGENTS.md）**：以规范包最新版为准，除非业务项目有特殊定制需求
- **端专属规范（harness/{端}/AGENTS.md）**：优先合并规范包更新，业务项目的定制规则追加到文件末尾
- **活文档**：业务项目自行追加的规则（来自真实失败案例）应保留，不受规范包更新影响
- **模板文件**：对比后选择性合并，注意保护已替换的模板变量

---

## 9. 规范文件速查

| 文件 | 用途 | 何时读取 |
|---|---|---|
| `AGENTS.md` | 任务流程、规范索引 | 始终读取 |
| `CLAUDE.md` | Claude Code 项目上下文 | Claude 自动加载 |
| `openspec/AGENTS.md` | OpenSpec 四阶段工作流 | 需求/设计阶段 |
| `openspec/config.yaml` | proposal/design/specs/tasks 编制规则 | 编写规范文档时 |
| `openspec/project.md` | 项目技术栈、架构约束 | 始终读取 |
| `harness/common/AGENTS.md` | 通用编码规范、安全规则、活文档机制 | 始终读取 |
| `harness/server/AGENTS.md` | 后端专属规则 + 模板索引 | 编写后端代码时 |
| `harness/portal/AGENTS.md` | 普通前端专属规则 + 模板索引 | 编写普通前端代码时 |
| `harness/admin-portal/AGENTS.md` | 后台管理前端专属规则 + 模板索引 | 编写后台管理前端代码时 |
| `harness/applet/AGENTS.md` | 小程序专属规则 + 模板索引 | 编写小程序代码时 |
| `harness/project-layout.md` | 目录结构、模板变量表、启动流程 | 创建项目/文件时 |
| `harness/git-rules.md` | 分支管理、提交信息格式 | 执行 Git 操作时 |
| `harness/test-rules.md` | 测试规范、自测检查清单 | 编写/运行测试时 |

---

## 10. 常见问题

### Q1：规范包和业务项目的代码冲突了怎么办？

规范包本身不包含可执行代码，只有 `.md` 规范文件和代码模板。业务项目的真实源代码在各自 `{project}-server/`、`{project}-portal/` 等目录下，与规范包目录互不重叠，不会冲突。

### Q2：业务项目可以修改规范文件吗？

可以，但建议采用**追加而非覆盖**的策略：
- 通用规则需要修改 → 追加到 `harness/common/AGENTS.md` 末尾
- 端专属规则需要修改 → 追加到对应端 `AGENTS.md` 末尾
- 这样规范包升级时，可以通过 diff 快速识别业务项目的定制内容

### Q3：OpenSpec 的 `changes/` 目录需要提交到 git 吗？

不需要。`openspec/changes/` 是进行中变更的工作区，已加入 `.gitignore`。只有归档后的 `openspec/specs/` 需要提交。

### Q4：没有使用 Claude Code，用其他 AI 工具也能用吗？

可以。将 `AGENTS.md` 的内容作为 system prompt 或项目上下文提供给 AI 即可。`CLAUDE.md` 是 Claude Code 专属，其他工具可忽略。

---

## License

MIT