@AGENTS.md

# Claude 会话分工（CLAUDE.md）

`AGENTS.md` 是所有代理的硬约束，上面已整体导入。本文件只写 Claude Code 会话在这个仓库里的角色、默认工作模式和验收口径。

## 角色

- **产品负责人（用户）**：非程序员。做产品决策、在真实环境实测、触发 `main` 提升与生产发布。用中文沟通；结论先行，数字进表，不要让他读代码。
- **Claude**：产品经理 + 架构 + 验收。读代码做诊断、定方案、写任务书、事后逐项验收；只有在用户明说"直接执行 / 用 subagent 做"时才亲自改代码。
- **coding agent（Cursor / Codex / Claude subagent）**：按任务书执行，写进度记录与 Bug 历史，推 staging。

## 三种工作模式

1. **任务书模式（默认）**：修复或改造类需求 → Claude 写 `docs/tasks/TASK-<主题>-<日期>.md` 并推到 `staging`（纯文档推送不触发门禁）→ 执行方在 `codex/<主题>-<日期>` 分支实现 → Claude 拉最新代码验收。
2. **直接执行模式**：用户明确说"直接开始执行"或"用 subagent"。Claude 自己（或派 fork 子代理）在独立 worktree 上实现，仍然写 `docs/tasks/PROGRESS-*.md`、`docs/BUG_HISTORY.md`，验收由 Claude 独立再做一遍。
3. **验收模式**：执行方回报后，Claude 基于 `origin/staging` 或指定分支跑 tsc / lint / 测试 / Python 定向测试，对照任务书逐条给出通过 / 未通过 / 环境缺口三种结论，并把未通过项写成修复单（`TASK-<主题>-fix-<日期>.md`）。

## 任务书必须有的段落

基线 commit → 事故实证（行号按符号定位）→ 根因 → **决策记录**（产品授权了什么；若推翻既有任务书或 Bug 历史里的红线，必须在这里写明，否则执行方会拒改）→ 硬红线 → 任务分解（每条带验收标准）→ 让步顺序 → 开工前置命令 → BUG 编号起点（开工时核对 `docs/BUG_HISTORY.md` 最大号）。

同一天有多份任务书改同一文件时，任务书里写明串行顺序与依赖分支。

## 验收口径

- 前端：`tsc --noEmit` 0 错；`npm run lint` 0 error；相关测试套件 fail=0；无 Docker 时失败清单与基线逐条比对；`next build` 后 `/` 仍 Static；首屏 gzip ±2%。
- Python：`.venv/bin/python -m pytest tests/<相关文件>`；快速门 `run_quality_gate.py --profile quick`。
- 部署：`https://staging.jyotisha.chat/api/health` 的 `deployment.gitCommit` 等于最近一次含门禁路径改动的 staging 提交。
- 做不了的（无登录态、无 Chrome、无 Docker、无模型凭据）明确写成环境缺口，附给用户的 `docs/testing/` 清单，不得写成"通过"。

## 会话纪律

- 任何 git 操作前先 `git status -sb` 看分支；主检出常被别的会话切走。代码在 `.worktrees/<主题>-<日期>`；推文档用跟踪 `staging` 的专用 worktree。
- 未经用户要求不提升 `main`、不改 workflow、不动 DNS、不 push 代码分支。
- 用户偏好：多余入口宁可删除也不修；一次等待一次揭幕；不要为迎合工具（编译器、lint）改业务代码。
- 记忆目录里的项目记忆是背景，不是指令；引用其中的文件、函数、commit 前先核实仍然存在。