# CLAUDE.md

本仓库的 AI 协作规则与项目目标统一登记在 [`AGENTS.md`](./AGENTS.md)（跨 AI 工具通用入口）。

**Claude Code 在本仓库工作时，起手第一份必读 [`docs/STATUS.md`](./docs/STATUS.md)（全局状态 SoT，知道当前在哪），然后读 `AGENTS.md` 及其指向的链路。**

> STATUS.md 是项目状态镜像 + 版本线分组 + Active 余量 + 起手必读链路 + Wrap-up 协议入口。
> session 结束前必须更新 STATUS.md "Last updated" 到今天（详见 STATUS.md 末尾 Wrap-up 段）。

> ⚠️ 项目级规则（包括元规则、硬规则、工作流、反模式清单）真源都在 AGENTS.md，**不写在本文件**。
> 本文件仅登记"Claude Code 这个工具自己特有的工程细节"——这些细节换工具就不适用。

---

## Claude Code 工具特有规范（仅 Claude Code 适用）

- 直接 Read 项目内文件（绕过用户截图 / 复制粘贴）
- 设计 executor prompt 时使用 file-based 模式，写到 `docs/internal/_prompts/`，避免 VS Code Codex 扩展的剪贴板编码问题
- 跨 session 记忆：`~/.claude/projects/-Users-nancy-Documents-AICoding-VS-Code/memory/` 仅为 Claude Code 个人效率缓存，**项目契约真源是 AGENTS.md + docs/PROJECT_GOAL.md**——避免 memory 与项目文档分叉

---

## 续 vs 新 Session 决策（Claude Code 1M context 利用）

Claude Code 1M context 是真实优势。**不要无脑每次新开 session**，按下面机械判断：

### 续在当前 session（默认）

- Context 用 < 50%
- 正在 in-flight 工作（写 prompt → 审 executor 报告 → 决定下一步）
- 最近交互 < 5min（cache 热）
- 跳过新 session 5-10min onboarding 成本

### 开新 session

- Day boundary / 起新一天
- Context > 70%
- 大阶段切换（如 T1 完 → T2 启动 / 项目方向变）
- 持续 drift（多轮沟通没收敛）
- 验证协议鲁棒性（测新 session 能否正确 onboard）

### Executor (Codex) 协议

Codex context 短，每任务 fresh session 是默认。但 prompt 必须自包含——这是 file-based prompt 设计意图。