代理配置

通过 AGENTS.md 指令和最佳实践配置 AI 编码代理以有效使用 HarnSpec。

AGENTS.md 概述

AGENTS.md 作为您仓库中 AI 编码代理的永久指令。当您运行 harnspec init 时，会创建此文件并包含 HarnSpec 指导。

用途：

提供项目上下文
定义何时使用 Spec
指定工作流程和命令
设置质量标准

Agent Skills（SKILL.md）

HarnSpec 现在支持 Agent Skills 的 SKILL.md 文件。推荐将 SDD 方法论 放入 SKILL.md，让 AGENTS.md 只保留项目特定规则。

项目级 Skill 位置：

.github/skills/HarnSpec-sdd/SKILL.md（通过 harnspec skill install 安装）

为什么使用 Skill？

跨平台：可用于 Claude、Cursor、Codex 等支持 Skills 的工具
可移植：纳入 git 管理，跨项目共享
AGENTS.md 精简：控制在 100 行以内，只写团队规则

最小化 AGENTS.md 示例（配合 Skill）：

# AI 代理指令

## 项目：Example

核心 SDD 工作流定义在 .github/skills/HarnSpec-sdd/SKILL.md。

## 项目特定规则
- 使用 pnpm 而非 npm
- UI 文案同时更新 en 与 zh-CN 语言包

多工具支持

不同的 AI 工具期望不同的指令文件名。HarnSpec 自动创建符号链接以确保所有工具都能找到指令：

AI 工具	期望的文件	HarnSpec 处理方式
Claude Code / Claude Desktop	`CLAUDE.md`	符号链接 → AGENTS.md
Gemini CLI	`GEMINI.md`	符号链接 → AGENTS.md
GitHub Copilot	`AGENTS.md`	主文件
Cursor	`AGENTS.md`	主文件
Windsurf	`AGENTS.md`	主文件
Cline	`AGENTS.md`	主文件
Warp Terminal	`AGENTS.md`	主文件

初始化选项

# 默认：创建 CLAUDE.md 符号链接（最常见用例）
harnspec init -y

# 为特定工具创建符号链接
harnspec init -y --agent-tools claude,gemini

# 为所有支持的工具创建符号链接
harnspec init -y --agent-tools all

# 跳过符号链接（旧行为）
harnspec init -y --agent-tools none

注意： 在 Windows 上，由于符号链接需要管理员权限，会创建副本而非符号链接。

以 CLI 为中心的 AGENTS.md

生成的 AGENTS.md 强调 CLI 命令配合 Agent Skills 进行 Spec 管理：

关键章节

1. 关键发现步骤

## 🚨 关键：任何任务之前

**先停下来检查这些：**

1. **发现上下文** → 使用 `harnspec board` 查看项目状态
2. **搜索相关工作** → 创建新 Spec 之前使用 `harnspec search`
3. **永远不要手动创建文件** → 始终使用 `harnspec create` 创建新 Spec

2. CLI 命令与 Agent Skills

## 🔧 如何管理 Spec

### 推荐方法：CLI 命令 + Agent Skills

AI 助手应通过运行 `harnspec` CLI 命令来获取信息和执行操作：

| 操作 | 命令 | 描述 |
|------|------|------|
| 查看项目状态 | `harnspec board` | 看板视图 + 项目健康指标 |
| 列出所有 Spec | `harnspec list` | 可过滤的带元数据列表 |
| 搜索 Spec | `harnspec search "query"` | 跨所有内容的语义搜索 |
| 查看 Spec | `harnspec view <spec>` | 带格式的完整内容 |
| 创建新 Spec | `harnspec create <name>` | 自动编号，正确结构 |
| 更新 Spec | `harnspec update <spec> --status <status>` | 验证状态转换，时间戳 |
| 检查依赖 | `harnspec deps <spec>` | 可视化依赖图 |

3. SDD 工作流检查点

## ⚠️ SDD 工作流检查点

### 开始任何任务之前
1. 📋 **运行 `board`** - 当前项目状态是什么？
2. 🔍 **运行 `search`** - 是否已有相关 Spec？
3. 📝 **检查现有 Spec** - 这项工作是否已有 Spec？

### 实现过程中
4. 📊 **编码前将状态更新为 `in-progress`**
5. 📝 **在 Spec 中记录决策**
6. 🔗 **如果发现关联，链接相关 Spec**

### 完成工作后
7. ✅ **完成后将状态更新为 `complete`**
8. 📄 **在 Spec 中记录学到的内容**
9. 🤔 **如需后续工作，创建新 Spec**

4. 常见错误表

### 🚫 避免常见错误

| ❌ 不要 | ✅ 应该 |
|--------|--------|
| 手动创建 Spec 文件 | 使用 `create` 工具 |
| 跳过发现直接开始新工作 | 先运行 `board` 和 `search` |
| 开始后保持状态为 "planned" | 立即更新为 `in-progress` |
| 完成工作但不更新 Spec | 记录决策，更新状态 |
| 手动编辑 frontmatter | 使用 `update` 工具 |
| 对话中忘记 Spec | 定期检查 Spec 状态 |

完整的 AGENTS.md 模板

# AI 代理指令

## 项目：[您的项目名称]

[项目功能的简要描述]

## 🚨 关键：任何任务之前

**先停下来检查这些：**

1. **发现上下文** → 使用 `board` 工具查看项目状态
2. **搜索相关工作** → 创建新 Spec 之前使用 `search` 工具
3. **永远不要手动创建文件** → 始终使用 `create` 工具创建新 Spec

> **为什么？** 跳过发现会导致重复工作。手动创建文件会破坏 HarnSpec 工具链。

## 🔧 如何管理 Spec

### 推荐方法：CLI 命令 + Agent Skills

AI 助手应通过运行 `harnspec` CLI 命令来获取信息和执行操作：

| 操作 | 命令 | 描述 |
|------|------|------|
| 查看项目状态 | `harnspec board` | 看板视图 + 项目健康指标 |
| 列出所有 Spec | `harnspec list` | 可过滤的带元数据列表 |
| 搜索 Spec | `harnspec search "query"` | 跨所有内容的语义搜索 |
| 查看 Spec | `harnspec view <spec>` | 带格式的完整内容 |
| 创建新 Spec | `harnspec create <name>` | 自动编号，正确结构 |
| 更新 Spec | `harnspec update <spec> --status <status>` | 验证状态转换，时间戳 |
| 检查依赖 | `harnspec deps <spec>` | 可视化依赖图 |

**为什么选择 CLI + Skills？**
- ✅ **广泛兼容**：几乎所有 AI 代理都支持执行 shell 命令。
- ✅ **方法论引导**：通过 SKILL.md 深度指导 AI 如何正确执行 SDD 流程。
- ✅ **易于测试**：人类和 AI 使用完全相同的命令。
- ✅ **轻量级**：无需复杂的外部服务器配置和维护。

## ⚠️ SDD 工作流检查点

### 开始任何任务之前
1. 📋 **运行 `board`** - 当前项目状态是什么？
2. 🔍 **运行 `search`** - 是否已有相关 Spec？
3. 📝 **检查现有 Spec** - 这项工作是否已有 Spec？

### 实现过程中
4. 📊 **编码前将状态更新为 `in-progress`**
5. 📝 **在 Spec 中记录决策**
6. 🔗 **如果发现关联，链接相关 Spec**

### 完成工作后
7. ✅ **完成后将状态更新为 `complete`**
8. 📄 **在 Spec 中记录学到的内容**
9. 🤔 **如需后续工作，创建新 Spec**

### 🚫 避免常见错误

| ❌ 不要 | ✅ 应该 |
|--------|--------|
| 手动创建 Spec 文件 | 使用 `create` 工具 |
| 跳过发现直接开始新工作 | 先运行 `board` 和 `search` |
| 开始后保持状态为 "planned" | 立即更新为 `in-progress` |
| 完成工作但不更新 Spec | 记录决策，更新状态 |
| 手动编辑 frontmatter | 使用 `update` 工具 |
| 对话中忘记 Spec | 定期检查 Spec 状态 |

## 核心规则

1. **首先阅读 README.md** - 了解项目上下文
2. **检查 specs/** - 开始前审查现有 Spec
3. **使用 CLI 命令** - 始终使用 `harnspec` CLI 命令
4. **遵循 HarnSpec 原则** - 清晰度优于文档
5. **保持最小** - 如果不增加清晰度，就删除它
6. **永不手动编辑 frontmatter** - 使用 `update`、`link`、`unlink` 工具
7. **在 Spec 中跟踪进度** - 更新状态并记录决策

## 何时使用 Spec

**为以下内容编写 Spec：**
- 影响系统多个部分的功能
- 破坏性更改或重大重构
- 需要团队对齐的设计决策

**跳过 Spec：**
- 错误修复
- 琐碎更改
- 不言自明的重构

## 质量标准

- **状态跟踪是必须的：**
  - `planned` → 创建后
  - `in-progress` → 开始实现之前
  - `complete` → 完成实现之后
- Spec 与实现保持同步
- 永不留下过时状态的 Spec

## Spec 复杂度指南

| Token 数 | 状态 |
|---------|------|
| <2,000 | ✅ 最佳 |
| 2,000-3,500 | ✅ 良好 |
| 3,500-5,000 | ⚠️ 考虑拆分 |
| >5,000 | 🔴 应该拆分 |

使用 `tokens` 工具检查 Spec 大小。

配置不同的 AI 工具

Claude Code

Claude Code 默认读取 CLAUDE.md。HarnSpec 自动创建此符号链接：

# harnspec init 后
ls -la CLAUDE.md
# CLAUDE.md -> AGENTS.md

核心提示： 配置 HarnSpec Agent Skills 以获得完整的功能指导。参见 Agent Skills 安装。

Gemini CLI

Gemini CLI 读取 GEMINI.md。创建方式：

harnspec init -y --agent-tools gemini

GitHub Copilot

Copilot 在编辑器中打开文件时自动读取 AGENTS.md。

无需额外设置。

Cursor

Cursor 默认读取 .cursorrules。选项：

选项 1： 使用 AGENTS.md（推荐）

# Cursor 也读取 AGENTS.md
# 无需额外设置

选项 2： 将 .cursorrules 链接到 AGENTS.md

ln -s AGENTS.md .cursorrules

Windsurf

Windsurf 默认读取 AGENTS.md。无需额外设置。

Claude Desktop / ChatGPT / 其他聊天界面

对于纯聊天界面，可以通过安装 Agent Skills 并根据其指导手动或半自动执行 CLI 命令。

AI 可读 Spec 的最佳实践

1. 明确和具体

❌ 模糊：

实现安全认证

✅ 具体：

实现 JWT 认证，包括：
- bcrypt 密码哈希（最少 10 轮）
- 24 小时 Token 过期
- 速率限制（每分钟每 IP 5 次尝试）

2. 提供示例

AI 代理更好地理解示例而不是抽象描述。

好：

## API 响应示例

\`\`\`json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-11-03T06:00:00Z",
  "user": {
    "id": "user_123",
    "email": "user@example.com"
  }
}
\`\`\`

3. 使用可测试的验收标准

使标准具体且可验证：

✅ 好标准：

POST /api/auth/login 成功时返回 200 和 JWT
无效凭据返回 401 和错误消息
密码使用 bcrypt 哈希，最少 10 轮
速率限制：每分钟每 IP 最多 5 次尝试

❌ 坏标准：

认证有效
良好的安全性
快速性能

4. 明确定义边界

使用"不在范围内"或"非目标"来防止范围蔓延：

## 不在范围内

- 社交登录（Google、GitHub）- 单独的史诗
- 密码重置 - 单独的 Spec
- 2FA - MVP 不需要
- 记住我功能 - 未来增强

5. 展示，不仅仅是告诉

包括具体示例：

API 请求/响应
CLI 命令和输出
数据库模式
配置文件
测试用例

6. 为扫描而构建

AI 代理（和人类）在阅读前扫描：

✅ 好结构：

## 问题
[2-3 句话]

## 解决方案
[高级方法]

### 技术细节
[实现细节]

## 成功标准
- [ ] [可测试的结果]

❌ 坏结构：

所以我们需要构建这个功能，它应该做 X、Y、Z...
[没有结构的大段文字]

仓库组织

使 Spec 可发现

your-project/
├── AGENTS.md           ← 主要 AI 指令
├── CLAUDE.md → AGENTS.md   ← Claude Code 的符号链接
├── README.md           ← 项目概述
├── specs/              ← 所有 Spec 在这里
│   ├── 001-feature-a/
│   │   └── README.md
│   ├── 002-feature-b/
│   │   ├── README.md
│   │   ├── DESIGN.md
│   │   └── TESTING.md
│   └── archived/       ← 旧 Spec
├── src/                ← 源代码
└── tests/              ← 测试

保持 Spec 靠近代码

仓库中的 Spec（不是外部 wiki）：

✅ 版本控制
✅ 分支特定
✅ AI 易于查找
✅ 可搜索

验证

测试 AI 理解

向您的 AI 代理提出这些问题以验证 HarnSpec 集成：

测试 1：它能发现项目吗？

显示项目看板。

预期：代理使用 harnspec board 命令。

测试 2：它能搜索 Spec 吗？

查找与认证相关的 Spec。

预期：代理使用 harnspec search 命令。

测试 3：它能正确创建 Spec 吗？

为用户认证创建一个 Spec。

预期：代理使用 harnspec create 命令（而非手动创建文件）。

测试 4：它能更新状态吗？

将 Spec 001 标记为进行中。

预期：代理使用 harnspec update 命令。

测试 5：它遵循 SDD 工作流吗？

我想实现一个新的缓存功能。

预期：代理先运行 board 和 search，然后在编码前创建 Spec。

常见陷阱

1. 过于冗长的指令

❌ 坏：

AI 代理应该仔细阅读所有可用的文档
并在进行任何更改之前彻底了解代码库。
重要的是...
[500 字的一般建议]

✅ 好：

首先阅读 README.md
使用 `harnspec list` 检查现有 Spec
遵循 HarnSpec 原则（见 AGENTS.md）

2. 模糊的成功标准

❌ 坏：

- [ ] 功能运行良好
- [ ] 良好的性能
- [ ] 用户满意

✅ 好：

- [ ] API 响应 `<100`ms（p95）
- [ ] 1 周内零崩溃
- [ ] NPS 分数 >8

3. 缺少上下文

始终提供：

为什么：问题和动机
什么：具体要求
如何：方法和约束
何时：成功标准

下一步

Agent Skills - 方法论指导
编写 AI 可执行的 Spec - 实用模式
入门 - 初始设置指南

相关：CLI 参考了解完整的命令文档

AGENTS.md 概述​

Agent Skills（SKILL.md）​

多工具支持​

初始化选项​

以 CLI 为中心的 AGENTS.md​

关键章节​

1. 关键发现步骤​

2. CLI 命令与 Agent Skills​

3. SDD 工作流检查点​

4. 常见错误表​

完整的 AGENTS.md 模板​

配置不同的 AI 工具​

Claude Code​

Gemini CLI​

GitHub Copilot​

Cursor​

Windsurf​

Claude Desktop / ChatGPT / 其他聊天界面​

AI 可读 Spec 的最佳实践​

1. 明确和具体​

2. 提供示例​

3. 使用可测试的验收标准​

4. 明确定义边界​

5. 展示，不仅仅是告诉​

6. 为扫描而构建​

仓库组织​

使 Spec 可发现​

保持 Spec 靠近代码​

验证​

测试 AI 理解​

常见陷阱​

1. 过于冗长的指令​

2. 模糊的成功标准​

3. 缺少上下文​

下一步​