# 与 Claude Code 高效协作手册

本手册面向 AgentSec 项目的唯一开发者，指导你如何与 Claude Code 建立稳定、高效的工作节奏。

---

## 一、每日开始工作

每次打开项目，发送一条定向消息让 Claude 快速进入状态：

```
今天继续开发 AgentSec。请读一下 ROADMAP.md、CHANGELOG.md 和 git log --oneline -10，
告诉我当前进度和今天可以推进的事项。
```

Claude 会：
1. 读取 ROADMAP 和近期 commits
2. 汇报哪些任务在进行、哪些待开始
3. 给出 1-3 条今日建议

你只需确认或调整方向，不需要重新解释背景。

---

## 二、规划一个新功能（正确流程）

项目规定**重大设计决策必须先写 ADR，再动代码**（见 CLAUDE.md）。流程如下：

### 第一步：描述想法

用自然语言告诉 Claude 你想做什么，不需要技术细节：

```
我想给报告加一个 JSON 输出格式，方便接入 CI 系统判断是否通过。
```

Claude 会反问必要的约束条件（格式？触发方式？），然后给出 2-3 个方案及各自的权衡。

### 第二步：让 Claude 写 ADR

确认方向后说：

```
这个方案可以，帮我写 ADR，用 docs/adr/_template.md 的格式。
```

Claude 会生成 `docs/adr/000X-json-report-format.md` 并填写背景、决策、后果。

**你的职责**：读一遍 ADR，确认描述符合你的意图，有问题直接纠正，没问题说"ADR 没问题，可以开始实现"。

### 第三步：让 Claude 实现

```
ADR 没问题，开始实现 JSON 报告功能。
```

Claude 会按 ADR 约定的设计写代码，跑相关测试，报告结果。

---

## 三、向 Claude 布置具体编码任务

### 写法原则

**说目标，不说步骤。** Claude 知道代码库的结构，不需要你告诉它改哪个文件。

| 低效写法 | 高效写法 |
|---|---|
| "打开 runner.py，在第 42 行加一个参数…" | "给 runner 加一个 `--dry-run` 选项，只打印测试列表不发请求" |
| "你知道怎么写 HTTP 客户端吗？" | "帮我给 OpenClaw 写一个 Adapter，接口文档在 docs/openclaw-api.md" |
| "先做 A 再做 B 再做 C" | "实现 X 功能"（让 Claude 拆分步骤） |

### 有用的附加信息

- **约束条件**：`只改 adapters/ 目录，不动评判器`
- **验收标准**：`跑完 tests/ 全绿才算完成`
- **参考资料**：`参考 ADR-0001 里的接口约定`

### 示例

```
帮我实现 HttpAgentAdapter 的 mock server 集成测试。
要求：在 tests/adapters/ 下新增，用 pytest，不依赖外部服务，模拟一个标准 HTTP target。
参考 writing-adapters.md 里对 Adapter 接口的描述。
```

---

## 四、让 Claude 更新进度

### 更新 ROADMAP

```
Phase 2 的 "Adapter 开发文档" 这一项已经完成了，帮我更新 ROADMAP.md 和 CHANGELOG.md。
```

Claude 会在 ROADMAP 打勾、在 CHANGELOG 加版本条目，并提交 commit。

### 更新 CHANGELOG（发布前）

```
准备发 v0.2.0，帮我整理 CHANGELOG，把 Phase 2 已完成的内容归入这个版本。
```

### 查询当前进度

```
当前哪些 Phase 2 的任务还没完成？
```

---

## 五、常用工作指令速查

| 意图 | 说法示例 |
|---|---|
| 了解现状 | "当前进度怎样？" |
| 规划新功能 | "我想做 X，给我方案" |
| 写 ADR | "帮我写 ADR，功能是 X" |
| 开始编码 | "ADR 没问题，开始实现" |
| 只读代码不改 | "解释一下 judge.py 的评判逻辑" |
| 跑测试 | "跑一下所有测试，告诉我结果" |
| 审查改动 | "我刚写了 X，帮我 review 一下" |
| 提交代码 | "测试都过了，帮我 commit" |
| 更新进度文档 | "把 X 任务标记为完成，更新 ROADMAP" |

---

## 六、你需要做的事，Claude 不替你做的事

Claude 会写代码、跑测试、写文档、管理 git，但以下事项需要你亲自决策：

| 事项 | 原因 |
|---|---|
| 确认 ADR 设计 | ADR 代表你的架构意图，Claude 起草但你负责 |
| 决定功能优先级 | ROADMAP 顺序由你的业务判断决定 |
| 审查敏感操作 | push 到远程、删除分支等需要你明确批准 |
| 提供 API Key | 目标 Agent 的凭证由你保管，写入 `.env`，不进代码 |
| 最终测试确认 | Claude 报告测试通过，你决定是否发版 |

---

## 七、维持长期上下文的技巧

Claude 每次对话都从零开始，没有跨会话记忆（除非写入 memory 文件）。为了维持连贯性：

1. **ROADMAP.md 是你们共同的看板**：每次开始工作先让 Claude 读它。
2. **CHANGELOG.md 是已做事项的记录**：避免重复问"上次做了什么"。
3. **ADR 是架构决策的档案**：不要口头约定设计，写进 ADR。
4. **git log 是最可靠的进度记录**：commit message 写清楚做了什么。
5. **在对话开头给足背景**：如果你换了话题或换了功能，简短说明一句。

---

## 八、纠正 Claude 的方法

Claude 理解直接的反馈，不需要委婉：

- "不对，你误解了需求，我要的是 X 不是 Y"
- "这个方案太复杂了，有没有更简单的做法"
- "回滚这个改动，我们换一个思路"
- "你刚才写的代码有个问题：……"

Claude 会承认并调整，不需要你解释为什么要纠正。

---

## 九、快速参考：项目关键约定

这些约定来自 CLAUDE.md，每次实现功能时 Claude 会自动遵守，但你也应该了解：

- `judge.py` 里的 `_SYSTEM` 是版本化行为，改动要慎重
- 测试用例 ID 全局唯一，前缀区分类别（`pi-`、`dl-`、`ta-`）
- Adapter 不能把 API Key 暴露到报告或日志中
- 重大设计必须先写 ADR，再动代码
- 环境变量写 `.env`（已在 `.gitignore`），不硬编码

---

> 本手册随项目演进更新。如有新的工作方式发现有效，可随时告诉 Claude "把这条加进操作手册"。
