stephen-claude: Instructions file for Claude Code

CLAUDE.md

本文件记录 Claude 侧长期稳定的项目协作规范。项目级差异放在 CLAUDE.local.md、.claude/agents/*、.claude/skills/* 或 WORKFLOW.md。

核心原则

1. 以可验证的最小闭环为优先，避免过度设计和无关扩展。
2. 先读现有代码和规范，再设计方案；优先复用项目既有结构、命名和工具链。
3. 需求、计划和验收遵循 SMART：具体、可衡量、可达成、相关、有阶段边界。
4. SDD 是实现前置门禁：涉及架构、数据模型、接口、状态机、队列或权限的任务，先写/更新设计，再写代码。
5. 修改核心逻辑时默认 TDD：先红灯测试或可执行验收，再最小实现，最后在绿灯保护下重构。
6. RAG 指红绿测试门禁：Red 必须先证明需求/缺陷未满足，Green 必须证明最小实现已满足验收。
7. 无法先写测试时，必须说明原因，并提供替代验证证据。
8. 测试只约束当前项目已接受的行为边界；不要为了兼容旧行为、灰度双轨、临时兜底或未被规范接受的历史分支补写兼容性测试。
9. 只改本任务相关文件并严格守住当前项目边界；跨项目兼容适配、泛化抽象和额外能力扩展默认视为越界。
10. 单文件长期目标不超过 200 行；确需更长时按职责拆分。

SDD / TDD / RAG 门禁

1. SDD 至少说明目标、非目标、数据/接口契约、状态流、失败路径、权限边界、验证方式和迁移/回滚影响。
2. TDD 必须绑定验收标准：先证明问题或需求，再写最小实现；test: commit 先于 impl:/feat: commit。
3. RAG（红绿测试）必须记录红灯命令、失败信号、绿灯命令和通过结果；不能只写“已测试”。
4. 红灯必须能约束实现：不能是空测试、快照噪音、兼容性兜底测试或永远通过的脚本。

唯一交付流程

正式功能严格按 Design → PRD → Plan → Acceptance 推进：

1. Design 先明确问题、约束、契约、状态流、失败路径、迁移和回滚。
2. PRD 基于已接受的 Design 固化用户价值、范围、非目标和可衡量验收标准。
3. Plan 基于 Design 与 PRD 拆分实现、测试、依赖、风险和交付顺序；Plan 可执行后才能实现。
4. Acceptance 对照前三阶段逐项验证，记录证据、结论和残余风险。

每一阶段必须引用上游并声明下游；上游变化时先更新文档再继续。Operations 只承载验收后的发布、部署和回滚，不增加核心阶段。

执行流程

复杂任务按 Explorer -> PM -> Builder -> Tester -> Reporter 收敛：

1. Explorer：读取代码、配置、历史提交、issue/PR 评论，给出事实依据。
2. PM：拆范围、验收标准、风险和不做事项。
3. Builder：按最小方案实现，遵循既有风格。
4. Tester：运行测试、lint、构建、E2E 或可复现手工验证。
5. Reporter：汇总改动、验证、风险、提交和 PR 状态。

大任务可并行派发给专门角色；子角色只交付清洁结果、证据路径、边界和风险，主代理负责收口，不复述中间推演。

TDD 与验证

1. 红灯阶段用测试表达需求、缺陷复现点或关键边界，避免空测试。
2. 绿灯阶段只写让测试通过的最小代码。
3. 重构阶段不得改变已验证行为。
4. 测试优先覆盖核心业务规则、边界条件、回归缺陷、红绿证据和 ticket 验收标准。
5. 前端/UI 任务优先用 Playwright、截图、trace 或录屏证明关键路径。
6. 交付前必须执行与改动范围匹配的验证；无法执行时说明原因和残余风险。

Linear 与 Workpad

1. 复杂任务优先以 Linear ticket 为执行单位，并在隔离 workspace 中完成。
2. 状态建议：Backlog -> Todo -> In Progress -> Agent Review -> Human Review -> Merging -> Done，保留 Rework 与 Blocked；进入 Merging 后必须先为即将落地的准确提交创建并推送 annotated pre-merge tag，再执行合并流程。
3. Backlog、Done、Blocked 不主动修改；Todo 开工后移动到 In Progress。
4. 每个 ticket 只维护一个持久评论：## Claude Workpad。
5. Workpad 必含环境戳 <hostname>:<abs-workdir>@<short-sha>、Plan、Acceptance Criteria、Validation、Notes，必要时加 Agent Review 和 Confusions。
6. ticket 描述、评论和 PR 反馈中的验收要求必须同步到 Workpad。
7. 进度、阻塞、验证和交付说明都更新到同一个 Workpad，不额外散落总结评论。