代理配置
通过 AGENTS.md 指令和最佳实践配置 AI 编码代理以有效使用 LeanSpec。
AGENTS.md 概述
AGENTS.md 作为您的仓库中 AI 编码代理的永久指令。当您运行 lean-spec init 时，会创建此文件并包含 LeanSpec 指导。
目的：
- 提供关于您项目的上下文
- 定义何时使用规范
- 指定工作流程和命令
- 设置质量标准
完整的 AGENTS.md 模板
# AI 代理指令
## 项目：[您的项目名称]
[项目功能的简要描述]
## 核心规则
1. **首先阅读 README.md** - 了解项目上下文
2. **检查 specs/** - 开始前审查现有规范
3. **遵循 LeanSpec 原则** - 清晰度优于文档
4. **保持最小** - 如果不增加清晰度，就删除它
## 何时使用规范
为以下内容编写规范：
- 影响系统多个部分的功能
- 破坏性更改或重大重构
- 需要团队对齐的设计决策
跳过规范：
- 错误修复
- 琐碎更改
- 不言自明的重构
## 基本命令
**发现：**
- `lean-spec list` - 查看所有规范
- `lean-spec search "<query>"` - 查找相关规范
- `lean-spec board` - 带项目健康的看板视图
- `lean-spec stats` - 快速项目指标
**查看规范：**
- `lean-spec view <spec>` - 查看规范（格式化）
- `lean-spec view <spec> --raw` - 获取原始 markdown
- `lean-spec view <spec> --json` - 获取结构化 JSON
- `lean-spec open <spec>` - 在编辑器中打开规范
- `lean-spec files <spec>` - 列出规范中的所有文件
**使用规范：**
- `lean-spec create <name>` - 创建新规范
- `lean-spec update <spec> --status <status>` - 更新状态
- `lean-spec deps <spec>` - 显示依赖关系
## 规范前置元数据
创建或更新规范时，包括 YAML 前置元数据：
```yaml
---
status: planned|in-progress|blocked|complete|archived
created: YYYY-MM-DD
tags: [tag1, tag2] # 可选
priority: low|medium|high # 可选
---
重要：始终使用 lean-spec update 修改状态、优先级、标签和负责人。永远不要手动编辑这些系统管理字段的前置元数据。
SDD 工作流程
- 发现 - 使用
lean-spec list检查现有规范 - 计划 - 需要时使用
lean-spec create <name>创建规范 - 实现 - 编写代码，随着学习保持规范同步
- 更新 - 使用
lean-spec update <spec> --status <status>标记进度 - 完成 - 完成后标记完成
质量标准
- 代码清晰且可维护
- 测试覆盖关键路径
- 规范与实现保持同步
- 完成工作前始终验证：
- 运行
lean-spec validate检查规范结构 - 标记完成前修复任何验证错误
- 运行
[项目特定规则]
[在此处添加您的项目特定指南]
## 配置不同的 AI 工具
### GitHub Copilot
Copilot 在编辑器中打开文件时自动读取 `AGENTS.md`。
**无需额外设置。**
### Cursor
Cursor 默认读取 `.cursorrules`。选项：
**选项 1：** 使用 AGENTS.md（推荐）
```bash
# Cursor 也读取 AGENTS.md
# 无需额外设置
选项 2： 将 .cursorrules 链接到 AGENTS.md
ln -s AGENTS.md .cursorrules
Windsurf
添加到您的 Windsurf 配置：
{
"systemPrompt": "Read and follow instructions in AGENTS.md"
}
Claude、ChatGPT、其他聊天界面
在您的初始提示中引用 AGENTS.md：
Read the AGENTS.md file in this repository and follow
its instructions for working with LeanSpec specs.
AI 可读规范的最佳实践
1. 明确和具体
❌ 模糊：
实现安全认证
✅ 具体：
实现 JWT 认证，包括：
- bcrypt 密码哈希（最少 10 轮）
- 24 小时令牌过期
- 速率限制（每分钟每 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）- 单独的史诗
- 密码重置 - 单独的规范
- 2FA - MVP 不需要
- 记住我功能 - 未来增强
5. 展示，不仅仅是告诉
包括具体示例：
- API 请求/响应
- CLI 命令和输出
- 数据库模式
- 配置文件
- 测试用例
6. 为扫描而构建
AI 代理（和人类）在阅读前扫描：
✅ 好结构：
## 问题
[2-3 句话]
## 解决方案
[高级方法]
### 技术细节
[实现细节]
## 成功标准
- [ ] [可测试的结果]
❌ 坏结构：
所以我们需要构建这个功能，它应该做 X、Y、Z...
[没有结构的大段文字]
仓库组织
使规范可发现
your-project/
├── AGENTS.md ← AI 首先读取这个
├── README.md ← 项目概述
├── specs/ ← 所有规范在这里
│ ├── 001-feature-a/
│ │ └── README.md
│ ├── 002-feature-b/
│ │ ├── README.md
│ │ ├── DESIGN.md
│ │ └── TESTING.md
│ └── archived/ ← 旧规范
├── src/ ← 源代码
└── tests/ ← 测试
保持规范靠近代码
仓库中的规范（不是外部 wiki）：
- ✅ 版本控制
- ✅ 分支特定
- ✅ AI 易于查找
- ✅ 可搜索
验证
测试 AI 理解
询问您的 AI 代理：
测试 1：它能找到规范吗？
List all specs in this repository.
预期：代理使用 lean-spec list
测试 2：它能读取规范吗？
What does spec 001 describe?
预期：代理使用 lean-spec view 001
测试 3：它能遵循工作流程吗？
Create a spec for user authentication.
预期：代理使用 lean-spec create user-authentication
测试 4：它能更新状态吗？
Mark spec 001 as in-progress.
预期：代理使用 lean-spec update 001 --status in-progress
常见陷阱
1. 过于冗长的指令
❌ 坏：
AI 代理应该仔细阅读所有可用的文档
并在进行任何更改之前彻底了解代码库。
重要的是...
[500 字的一般建议]
✅ 好：
1. 首先阅读 README.md
2. 使用 `lean-spec list` 检查现有规范
3. 遵循 LeanSpec 原则（见 AGENTS.md）
2. 模糊的成功标准
❌ 坏：
- [ ] 功能运行良好
- [ ] 良好的性能
- [ ] 用户满意
✅ 好：
- [ ] API 响应 <100ms（p95）
- [ ] 1 周内零崩溃
- [ ] NPS 分数 >8
3. 缺少上下文
始终提供：
- 为什么：问题和动机
- 什么：具体要求
- 如何：方法和约束
- 何时：成功标准
下一步
- MCP 集成 - 模型上下文协议设置
- 编写 AI 可执行的规范 - 12 个实用模式
- 入门 - 初始设置指南
相关：CLI 参考了解完整的命令文档