# [Project Name]

> **Template Version: v3.0.0** — 复制本文件为 `CLAUDE.md` 后填项目内容。Agent 角色用裸名（`product-lead` / `backend-dev` …），项目 skill / slash command 保留 `agf-` 前缀。详见根目录 `CHANGELOG.md` 与 `.claude/rules/team-mode.md`。

## Project Overview

[用 2-4 行描述这个项目的目标、主要用户、核心价值]

## Tech Stack

> 由 tech-lead 在项目启动时维护，每次技术选型变更必须新开 ADR + 同步此处。详细基线见 `docs/adr/000-system-architecture.md`。

| 类别 | 选型 | ADR |
|---|---|---|
| 前端框架 | [待填写] | [ADR-xxx 或 —] |
| 后端框架 | [待填写] | [ADR-xxx 或 —] |
| 数据库 | [待填写] | [ADR-xxx 或 —] |
| AI SDK | DeepSeek / Doubao / Qwen / MiniMax（多厂商，可裁剪） | — |
| 测试框架 | [待填写] | [ADR-xxx 或 —] |
| 代码风格 | [待填写] | — |
| 部署 | [待填写] | [ADR-xxx 或 —] |

## Project-Specific Rules

- 本文件只放项目特有规则，团队通用规则统一放在 `.claude/standards/`，结构性指引在 `.claude/rules/`。
- [填写项目特有约束：合规、网络、依赖、部署窗口等]
- [填写业务术语或不可变边界]
- 涉及多 LLM SDK 接入（DeepSeek/Doubao/Qwen/MiniMax 切换、fallback、env 变量）→ 必须先看 skill `agf-wiring-multi-llm-sdk`。
- 写 PRD → skill `agf-writing-prd`；写 ADR → skill `agf-writing-adr`。
- SIT 由执行层 dev 自跑（按 skill `agf-running-sit-tests`），证据落 `progress/<role>.md` 的 `**SIT 证据**` 段，由 `code-reviewer` 在 code review 时 audit。
- 写 E2E / UAT 报告 → skill `agf-writing-qa-report`（v2.0.0 rename，原 `agf-writing-sit-report`；SIT 不再单独成报告）。
- Release 推 tag + `gh release create` 完成后（仅 MAJOR / MINOR）→ 必须 `/agf-release-retro vX.Y.Z` 触发，按 skill `agf-running-release-retro`，产物归档到 `docs/reviews/retro-vX.Y.Z-YYYY-MM-DD.md`；PATCH 跳过。

## Verified Facts (Quick Reference)

> 跨 session 复用的"硬事实"缓存，引用前优先看此节；如不在此节，**grep 实际代码 verify 后再断言**（参见 `.claude/standards/coding.md` "Verify before assert"）。
>
> **此节与 `coding.md "Verify before assert"` 形成闭环**：第一次 verify 通过的事实写入此节，后续 session 直接查表即可，避免重复 grep 与基线引用误述。

**适合写进此节的事实类别**（按本项目实际填）：

- 鉴权机制（cookie / Bearer / session 等具体形式 + 实证文件路径）
- 关键 CLI / 管理命令（含完整参数与 subcommand）
- 默认测试账号 / 种子数据
- 配置文件位置 / 关键 env 变量
- 状态/锁定/限流等"实际存在位置"（数据库 / Redis / 内存）
- 任何"曾经被错误描述、最终 grep 修正"过的硬事实

**不适合写进此节**：变化频繁的状态、in-progress 任务、未来计划——那些归 task list / PRD / ADR。

**示例条目**（项目启动后替换为实际事实）：

- [待填] **Auth 机制**：[具体形式] — 实证 [实际代码路径:行号]
- [待填] **种子数据 / 默认账号**：[具体值] — 由 [初始化脚本路径] 创建
- [待填] **关键 CLI**：[完整命令含 subcommand 与必填参数]

> 项目启动初期此节可为空；发生第一次"基线引用错误链"事件（review/ADR/spec 因没 verify 而误述）后立即建立，往后越用越值钱。

## Test Commands

> 项目实际的测试入口固化在此，agent 跑测试时优先查此节，避免重新探索目录结构。tech-lead 在第一次跑通完整测试链路后填写，每次测试入口或前置条件变化时必须同步更新。

- **backend unit**：[待填写，例 `cd backend && pytest tests/unit/ -v`]
- **backend integration**：[待填写，注明是否需要特殊环境，例 testcontainers / Docker socket / 外部数据库]
- **frontend unit**：[待填写，例 `cd frontend && pnpm test`]
- **E2E**：[待填写，含必要的 env 变量与前置步骤，例 `docker compose up -d` + 创建测试账号]
- **lint / typecheck / format**：[待填写，例 `cd backend && ruff check . && mypy .` / `cd frontend && pnpm lint`]

> ⚠️ 命令变化（新增 testcontainers 依赖 / 改 E2E 命令 / 换包管理器）时必须同步本节，否则下一个 agent 会按过时命令跑，浪费一整轮交接。

## Tool Boundaries

四层 hook 防御（注册位置：`.claude/settings.json` + `.git/hooks/pre-commit`，文档：`.claude/standards/security.md`）：

1. **`PreToolUse` (Bash) — `block-dangerous-bash.sh`**：硬阻断 `rm -rf` / `DROP TABLE` / `git push --force` / `git reset --hard`。
2. **`UserPromptSubmit` — `scan-secrets.sh`**：硬阻断 AWS/GitHub/OpenAI/Anthropic/Google/Slack/DeepSeek/Doubao/Qwen/MiniMax 密钥 + PEM/SSH/PuTTY 私钥 + BIP39 助记词。
3. **`PostToolUse` (WebFetch/WebSearch/Read/Bash) — `sanitize-tool-output.sh`**：软告警外部内容里的 prompt-injection 指令。
4. **`pre-commit` (git) — `scan-commit.sh`**：commit 前对 staged diff 跑同套 secret 正则，防 Edit/Write 绕过 prompt 扫描。安装：`ln -sf ../../.claude/hooks/scan-commit.sh .git/hooks/pre-commit`（`init-team.sh` 会自动安装）。

`.claude/settings.json` 的 `permissions.deny` 已禁读 `.env*`、`~/.ssh/**`、`~/.aws/**`、`~/.gnupg/**` 等敏感路径，并禁 `curl|sh` / `eval` 等远程执行链路。

附加 workflow hooks（**不属于安全防御**，仅维护团队工作流）：

5. **`TeammateIdle` — `teammate-keepalive.sh`**：task list 还有 pending 时阻止 teammate 提前 idle。
6. **`UserPromptSubmit` — `skill-suggester.sh`**：按 `.claude/hooks/skill-rules.json` 软建议相关 skill / 命令；不阻断。
7. **`SubagentStop` / `TeammateIdle` — `check-progress-file.sh`**：执行层 role 退出时若 `progress/<role>.md` 缺 SIT 证据段则阻断（v2.0.0+ 兜底）。
8. **`PreToolUse` (TaskCreate) — `validate-task-schema.sh`**：派单前校验 task 6 段齐全（description / 上下游产物 / AC 等），漏字段阻断。

撞到硬阻断时按 `.claude/standards/security.md` "No Equivalent Bypass" 处理（不得寻找等价绕过）。

## Team Runtime Contract

本项目复用 `.claude/` 中的 AI 团队模板。权威来源：
- 角色与协作边界：`.claude/standards/team-roles.md`
- 工作流（含 Parallel Dispatch + worktree 强制）：`.claude/standards/workflow.md`
- 文档与单一来源原则：`.claude/standards/document-rules.md`
- Superpowers 使用规范：`.claude/standards/superpowers.md`
- 测试与验收：`.claude/standards/testing.md`、`.claude/standards/ac-lifecycle.md`
- 编码与安全：`.claude/standards/coding.md`、`.claude/standards/security.md`
- 观测与成本：`.claude/standards/observability.md`、`.claude/standards/cost-budget.md`
- 版本与发布：`.claude/standards/versioning.md`（SemVer 应用细则 + release 流程）
- 对话回复风格：`.claude/standards/communication.md`（所有 agent 面向人的回复精简，docs 产出物不受影响）

仓库目录约定见 `.claude/rules/repo-layout.md`；Team Mode 启动协议（≥2 角色 / 跨链路任务必须 spawn agent team）见 `.claude/rules/team-mode.md`——两者按 path 自动加载。

运行时关键约束（摘要，细则以权威来源为准）：

- `.claude/standards/team-roles.md` 是角色额外工具与预加载 skills 的唯一团队级能力基线。
- `product-lead` 是唯一流程编排者；`tech-lead` 仅在缺少基线、新技术选型或架构风险升级时强制介入。
- 会话入口判断（直接执行 vs 派给 `product-lead`）见 `.claude/standards/workflow.md` "Session Entry" 节。
- 交付链路固定为 `代码实现 + Unit + SIT 自跑 → code review (含 SIT Audit) → E2E → UAT`；任一阶段失败后由 `product-lead` 重新分派执行层修复。
- `code-reviewer` 为 review-only 角色；`qa-engineer` 负责执行 E2E / UAT 并提交报告（集成层 SIT 由 dev 自跑、reviewer 审证据），最终业务签字由 `product-lead` 完成。
- `backend-dev` / `ai-agent-dev` 在高风险变更（schema 迁移、认证逻辑、LLM 提供商切换、生产 prompt 变更等）必须先进 Plan Mode 拿 product-lead 授权。
- token 消耗与成本按 `.claude/standards/cost-budget.md` 分级（含会话规模上限、cache 利用率 ≥ 60% 与 14 agent 默认 model 路由）；如需查看本次会话用量，跑 Claude Code 内置 `/usage`。
- 对话回复一律按 `.claude/standards/communication.md` 执行；写入 `docs/` 的产出物不压缩。

### 如本项目包含微信小程序（可选）

> 不含小程序的项目可整段删除本节、移除 `.claude/agents/agf-miniapp-*.md`、删除 `.claude/standards/miniapp.md`。

- 额外加载 `.claude/standards/miniapp.md`（小程序专项规范）
- 小程序设计由 `uiux-designer` 在 **MiniApp Mode** 下完成（不再独立 designer 角色）
- 小程序专项交付链路：`uiux-designer (MiniApp Mode) → miniapp-dev → miniapp-code-reviewer → miniapp-qa-engineer → product-lead`，与 Web 链路并行
- 设计交付路径区分：Web 走 `docs/design/[feature]/`，小程序走 `docs/design/[feature]-miniapp/`
- E2E 自动化标准：微信官方 `miniprogram-automator` + Jest（详见 `miniapp.md` 第 6 节），不引入第三方 MCP

若本文件中的项目规则与团队规范冲突，以本文件为准。
