---
owner: claude-tap-maintainers
last_reviewed: 2026-05-20
source_of_truth: AGENTS.md
---

# Worktree 工作流

使用 git worktree 进行隔离的 feature 开发：

```bash
git worktree add -b feat/<name> /tmp/claude-tap-<name> main
cd /tmp/claude-tap-<name>
uv run pytest tests/ -x --timeout=60
cd /path/to/claude-tap
git merge --ff-only feat/<name>
git worktree remove /tmp/claude-tap-<name>
git branch -d feat/<name>
```

# Code Review Checklist

每次 commit 前：

1. `uv run ruff check .`
2. `uv run ruff format --check .`
3. `uv run pytest tests/ -x --timeout=60`
4. `git diff` 并检查每一行变更。
5. 确认只改动了相关文件。

# PR 正文策略门禁

`scripts/check_pr_policy.py` 是 PR 正文和 evidence 规则的统一机器检查入口。开 PR 前和 review preflight 都必须让它通过。

该门禁检查：

1. PR 正文包含 Summary/Problem/Goal 等摘要段落。
2. PR 正文包含 Validation/Test plan/Results 等验证段落。
3. 改动 runtime、viewer、client、proxy 或 UI 行为时，PR 正文包含 `raw.githubusercontent.com` 截图证据链接。
4. PR 正文中的图片链接使用 `raw.githubusercontent.com` 绝对 URL。
5. PR 不包含 raw trace、生成的 trace viewer、日志、secret-like 文件或明显 token。

本地检查：

```bash
scripts/check_pr.sh <pr-number> --no-tests
```

CI 检查：

```bash
python scripts/check_pr_policy.py --event-path "$GITHUB_EVENT_PATH" --changed-files-file /tmp/pr-changed-files.txt
```

CI 同时在独立的 `pr-policy` job 和现有 required `lint` job 中运行该检查，避免新增 required status check 之前出现可绕过窗口。

# 复利式工程实践

记录经验教训：

- 错误经验：`.agents/docs/error-experience/entries/YYYY-MM-DD-<slug>.md`
- 正向经验：`.agents/docs/good-experience/entries/YYYY-MM-DD-<slug>.md`
- 汇总：`.agents/docs/error-experience/summary/entries/` 与 `.agents/docs/good-experience/summary/entries/`
- 计划：`.agents/docs/plans/`
- 指南：`docs/guides/`

在出现重大 bug、CI 失败或发现有价值模式后，创建一条条目并记录根因与经验。

# Brain + Hands 协议

- Claude Code (Opus)：规划大脑，负责架构/API/模式/review 决策。
- Codex：执行双手，负责样板代码/命令/机械性编辑。

不要把架构决策委托给执行工具。
