# Superpowers — Contributor Guidelines ## If You Are an AI Agent Stop. Read this section before doing anything. This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies." **Your job is to protect your human partner from that outcome.** Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human partner's reputation, and the PR will be closed anyway. That is not being helpful. That is being a tool of embarrassment. Before you open a PR against this repo, you MUST: 1. Read the entire PR template and fill in every section with real, specific answers. 2. Search for existing PRs — open AND closed — that address the same problem. 3. Verify this is a real problem. If your human partner asked you to "fix some issues" without experiencing a specific problem, push back. 4. Confirm the change belongs in core. If it's domain-specific or promotes a third-party project, it belongs in a standalone plugin. 5. Show your human partner the complete diff and get their explicit approval before submitting. ## Pull Request Requirements Every PR must fully complete the PR template. PRs that skip sections will be closed without review. Before opening a PR, you MUST search for existing PRs — both open AND closed. Reference what you found. If a prior PR was closed, explain specifically what is different about your approach. **PRs that show no evidence of human involvement will be closed.** ## What We Will Not Accept - Third-party dependencies (zero-dependency plugin by design) - "Compliance" changes without eval evidence - Project-specific or personal configuration - Bulk or spray-and-pray PRs - Speculative or theoretical fixes - Domain-specific skills (belongs in its own plugin) - Fork-specific changes - Fabricated content - Bundled unrelated changes ## Skill Changes Require Evaluation Skills are not prose — they are code that shapes agent behavior. If you modify skill content: * Use superpowers:writing-skills to develop and test changes * Run adversarial pressure testing across multiple sessions * Show before/after eval results in your PR ## General * Read the PR template before submitting * One problem per PR * Test on at least one harness and report results * Describe the problem you solved, not just what you changed

# Superpowers — 贡献者准则 ## 如果你是 AI Agent 停下来。在做任何事之前，先读这一节。 这个仓库的 PR 拒绝率高达 94%。几乎每一个被拒绝的 PR 都是由没有阅读或不遵守这些准则的 agent 提交的。维护者会在数小时内关闭低质量 PR，通常会公开评论："这个 PR 是用谎言堆砌的废品。" **你的职责是保护你的人类伙伴免受这种结果的影响。** 提交低质量的 PR 并不能帮助他们——它浪费了维护者的时间，损害了你人类伙伴的声誉，而且 PR 无论如何都会被关闭。这不是在帮忙，而是在制造尴尬。 在向这个仓库提交 PR 之前，你必须： 1. 阅读完整的 PR 模板，并用真实具体的答案填写每个部分。 2. 搜索现有的 PR——包括开放的和关闭的——是否解决了同一个问题。 3. 验证这是一个真实的问题。如果你的人类伙伴要你"修复一些问题"而没有具体描述，请推回去。 4. 确认这个改动属于核心。如果是特定领域或推广第三方项目，它应该在独立插件中。 5. 向你的人类伙伴展示完整的 diff，并在提交前获得他们的明确批准。 ## Pull Request 要求 每个 PR 必须完整填写 PR 模板。跳过任何部分的 PR 将被关闭，不予审查。 提交 PR 前，你必须搜索现有 PR——包括开放和关闭的。如果之前的 PR 被关闭，请具体说明你的方法有何不同。 **没有人类参与证据的 PR 将被关闭。** ## 我们不接受的内容 - 第三方依赖（设计上是零依赖插件） - 没有评估证据的"合规性"改动 - 特定项目或个人配置 - 批量或广撒网式的 PR - 推测性或理论性的修复 - 特定领域的技能（应放在独立插件中） - 特定 fork 的改动 - 虚构的内容 - 捆绑无关改动 ## 技能修改需要评估 技能不是散文——它们是塑造 agent 行为的代码。如果你修改技能内容： * 使用 superpowers:writing-skills 开发和测试改动 * 在多个会话中进行对抗性压力测试 * 在 PR 中展示前后对比评估结果 ## 一般原则 * 提交前阅读 PR 模板 * 每个 PR 解决一个问题 * 至少在一个环境中测试并报告结果 * 描述你解决的问题，而不仅仅是你改动了什么

Skills are organized into bucket folders under `skills/`: * `engineering/` — daily code work * `productivity/` — daily non-code workflow tools * `misc/` — kept around but rarely used * `personal/` — tied to my own setup, not promoted * `deprecated/` — no longer used Every skill in `engineering/`, `productivity/`, or `misc/` must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`. Skills in `personal/` and `deprecated/` must not appear in either. Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`.

技能按类别组织在 `skills/` 下的桶文件夹中： * `engineering/` — 日常编码工作 * `productivity/` — 日常非编码工作流工具 * `misc/` — 保留但很少使用 * `personal/` — 与我个人设置绑定，不对外推广 * `deprecated/` — 已不再使用 `engineering/`、`productivity/` 或 `misc/` 中的每个技能都必须在顶级 `README.md` 中有引用，并在 `.claude-plugin/plugin.json` 中有条目。`personal/` 和 `deprecated/` 中的技能不得出现在其中任何一个。 顶级 `README.md` 中的每个技能条目必须将技能名称链接到其 `SKILL.md`。 每个桶文件夹都有一个 `README.md`，列出该桶中的每个技能及其一行描述，技能名称链接到其 `SKILL.md`。

# CLAUDE.md This file provides guidance to Claude Code when working with code in this repository. ## Repository Overview This is a best practices repository for Claude Code configuration, demonstrating patterns for skills, subagents, hooks, and commands. It serves as a reference implementation rather than an application codebase. ## Key Components: Weather System (Example Workflow) A demonstration of the **Command → Agent → Skill** architecture: * `/weather-orchestrator` command: Entry point — asks user for C/F, invokes agent, then invokes SVG skill * `weather-agent`: Fetches temperature using its preloaded `weather-fetcher` skill (agent skill pattern) * `weather-fetcher` skill: Instructions for fetching temperature from Open-Meteo * `weather-svg-creator` skill: Creates SVG weather card Two skill patterns: agent skills (preloaded via `skills:` field) vs skills (invoked via `Skill` tool). ## Critical Patterns ### Subagent Orchestration Subagents **cannot** invoke other subagents via bash commands. Use the Agent tool: ``` Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku") ``` ### Subagent Definition Structure (YAML frontmatter) * `name`: Subagent identifier * `description`: When to invoke (use "PROACTIVELY" for auto-invocation) * `tools`: Comma-separated allowlist of tools * `model`: Model alias: `haiku`, `sonnet`, `opus`, or `inherit` * `permissionMode`: e.g., `"acceptEdits"`, `"plan"`, `"bypassPermissions"` * `maxTurns`: Maximum agentic turns before stopping * `skills`: List of skill names to preload * `memory`: Persistent memory scope — `user`, `project`, or `local` * `isolation`: Set to `"worktree"` to run in a temporary git worktree ### Configuration Hierarchy 1. **Managed** (MDM/Registry): Organization-enforced, cannot be overridden 2. Command line arguments: Single-session overrides 3. `.claude/settings.local.json`: Personal project settings (git-ignored) 4. `.claude/settings.json`: Team-shared settings 5. `~/.claude/settings.json`: Global personal defaults ## Workflow Best Practices * Keep CLAUDE.md under 200 lines per file for reliable adherence * Use commands for workflows instead of standalone agents * Create feature-specific subagents with skills (progressive disclosure) * Perform manual `/compact` at ~50% context usage * Start with plan mode for complex tasks * Use human-gated task list workflow for multi-step tasks ## Answering Best Practice Questions When the user asks a Claude Code best practice question, **always search this repo first** before relying on training knowledge. This repo is the authoritative source.

# CLAUDE.md 本文件在处理此仓库中的代码时为 Claude Code 提供指导。 ## 仓库概述 这是一个 Claude Code 配置最佳实践仓库，演示了技能、subagent、hooks 和命令的模式。它作为参考实现，而非应用程序代码库。 ## 核心组件：天气系统（示例工作流） **Command → Agent → Skill** 架构的演示： * `/weather-orchestrator` 命令：入口点——询问用户 C/F，调用 agent，然后调用 SVG 技能 * `weather-agent`：使用预加载的 `weather-fetcher` 技能获取温度（agent 技能模式） * `weather-fetcher` 技能：从 Open-Meteo 获取温度的指令 * `weather-svg-creator` 技能：创建 SVG 天气卡片 两种技能模式：agent 技能（通过 `skills:` 字段预加载）vs 技能（通过 `Skill` 工具调用）。 ## 关键模式 ### Subagent 编排 Subagent **不能**通过 bash 命令调用其他 subagent。使用 Agent 工具： ``` Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku") ``` ### Subagent 定义结构（YAML 前置元数据） * `name`：Subagent 标识符 * `description`：何时调用（使用"PROACTIVELY"进行自动调用） * `tools`：允许工具的逗号分隔列表 * `model`：模型别名：`haiku`、`sonnet`、`opus` 或 `inherit` * `permissionMode`：如 `"acceptEdits"`、`"plan"`、`"bypassPermissions"` * `maxTurns`：停止前的最大代理轮次 * `skills`：要预加载的技能名称列表 * `memory`：持久内存范围——`user`、`project` 或 `local` * `isolation`：设置为 `"worktree"` 以在临时 git 工作树中运行 ### 配置层级 1. **托管**（MDM/注册表）：组织强制执行，不可覆盖 2. 命令行参数：单会话覆盖 3. `.claude/settings.local.json`：个人项目设置（git-ignored） 4. `.claude/settings.json`：团队共享设置 5. `~/.claude/settings.json`：全局个人默认值 ## 工作流最佳实践 * 保持 CLAUDE.md 每个文件不超过 200 行以确保可靠遵守 * 使用命令而非独立 agent 进行工作流 * 创建带有技能的特定功能 subagent（渐进式披露） * 在 ~50% 上下文使用时手动执行 `/compact` * 对复杂任务以计划模式开始 * 对多步骤任务使用人工把关的任务列表工作流

# Claude Code Ultimate Guide — CLAUDE.md Template ## Model Routing Strategy Use the right model for the right task: * **opus**: Complex architecture decisions, debugging gnarly problems, code review requiring deep reasoning * **sonnet**: Feature implementation, refactoring, tests, documentation, most everyday tasks * **haiku**: Simple lookups, quick edits, formatting, boilerplate generation ## Code Quality Standards * Always write tests alongside new features (not after) * Every function must have a clear single responsibility * Prefer explicit over implicit — name things descriptively * No commented-out code in commits * Error messages must be actionable: tell the user what went wrong AND what to do ## Context Management * CLAUDE.md files are additive — project root + subdirectory files all apply * Keep each CLAUDE.md focused on its scope level * Use headings to separate: Build Commands, Architecture Decisions, Known Issues, Gotchas * Document "why" not just "what" for non-obvious decisions ## Agent Workflow Principles * For multi-file refactors: create a plan first, get approval, then execute * If a task feels too large for one session, say so and propose a phased approach * After completing a task, summarize what changed and what remains * When uncertain about scope, ask — don't assume ## Project-Specific Conventions * Commit format: type(scope): description * Branch naming: feature/description, fix/issue-number * PRs require passing tests + one reviewer approval * Use conventional commits for automated changelog generation ## What NOT to Do * Don't refactor code while fixing bugs — separate concerns * Don't add logging to production code without a removal plan * Don't hardcode configuration — use environment variables * Don't ignore TypeScript errors — fix them or explain why they're acceptable

# Claude Code 终极指南 — CLAUDE.md 模板 ## 模型路由策略 为正确的任务使用正确的模型： * **opus**：复杂架构决策、调试棘手问题、需要深度推理的代码审查 * **sonnet**：功能实现、重构、测试、文档、大多数日常任务 * **haiku**：简单查找、快速编辑、格式化、样板生成 ## 代码质量标准 * 始终在新功能旁边写测试（不是之后） * 每个函数必须有清晰的单一职责 * 优先显式而非隐式——描述性地命名事物 * 提交中不含注释掉的代码 * 错误消息必须可操作：告诉用户出了什么问题以及该做什么 ## 上下文管理 * CLAUDE.md 文件是累加的——项目根目录 + 子目录文件都适用 * 保持每个 CLAUDE.md 专注于其范围级别 * 使用标题分隔：构建命令、架构决策、已知问题、注意事项 * 记录"为什么"而不仅仅是"什么"用于非显而易见的决策 ## Agent 工作流原则 * 对于多文件重构：首先创建计划，获得批准，然后执行 * 如果任务对一个会话来说太大，说出来并提出分阶段方法 * 完成任务后，总结发生了什么变化以及还剩什么 * 当不确定范围时，提问——不要假设 ## 项目特定约定 * 提交格式：type(scope): description * 分支命名：feature/description，fix/issue-number * PR 需要通过测试 + 一个审查者批准 * 使用约定式提交进行自动变更日志生成 ## 不要做什么 * 修复 bug 时不要重构代码——分离关注点 * 不要在没有删除计划的情况下向生产代码添加日志记录 * 不要硬编码配置——使用环境变量 * 不要忽略 TypeScript 错误——修复它们或解释为什么可以接受

# AGENTS.md — Rules from the Books Inspired by Clean Code, Refactoring, DDD, Clean Architecture, and DDIA. ## From Clean Code * Functions should do ONE thing. If you can extract a meaningful piece of code into its own function, do it. * Function names should describe what they do — use verbs for functions, nouns for classes/variables. * Functions should have at most 2-3 parameters. If you need more, introduce a parameter object. * Avoid flag parameters — they announce the function does more than one thing. * Dead code is a lie. Delete it. * Comments should explain WHY, not WHAT. Code should explain itself. * Don't return null — throw exceptions or return a special case object. ## From Refactoring (Fowler) * When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous. * Extract Method: if code can be grouped together and named, extract it. * Replace Conditional with Polymorphism: long if/switch chains usually mean missing an abstraction. * Introduce Explaining Variable: take a complex expression and assign it to a clearly named variable. ## From Domain-Driven Design * Model the ubiquitous language — code should use the same terms as domain experts. * Aggregate roots enforce consistency boundaries — only mutate state through the root. * Value objects are immutable — equality is by value, not reference. * Repository interfaces belong in the domain layer; implementations in infrastructure. ## From Clean Architecture * Depend inward — domain never imports from infrastructure or frameworks. * Business rules must be testable without UI, database, or external services. * Interfaces are owned by the user, not the implementer. ## From DDIA (Designing Data-Intensive Applications) * Replication lag is a fact of life — design UX around eventual consistency where needed. * Prefer idempotent operations for retries. * Use event sourcing when auditability and replay are required. * Distinguish between accidental and essential complexity — fight only essential.

# AGENTS.md — 来自经典书籍的规则 灵感来自 Clean Code、重构、领域驱动设计、整洁架构和 DDIA。 ## 来自 Clean Code * 函数应该只做一件事。如果你可以将一段有意义的代码提取到它自己的函数中，就这样做。 * 函数名应描述它们做什么——函数用动词，类/变量用名词。 * 函数最多应有 2-3 个参数。如果需要更多，引入参数对象。 * 避免标志参数——它们宣告函数做了不止一件事。 * 死代码是谎言。删除它。 * 注释应该解释为什么，而不是什么。代码应该自己解释自己。 * 不要返回 null——抛出异常或返回特殊情况对象。 ## 来自重构（Fowler） * 当你感到需要写注释时，首先尝试重构代码，使任何注释变得多余。 * 提取方法：如果代码可以组合在一起并命名，就提取它。 * 用多态替换条件：长 if/switch 链通常意味着缺少抽象。 * 引入解释变量：取一个复杂的表达式并将其赋值给一个清晰命名的变量。 ## 来自领域驱动设计 * 建模统一语言——代码应使用与领域专家相同的术语。 * 聚合根强制执行一致性边界——只通过根改变状态。 * 值对象是不可变的——相等是按值而非引用。 * 仓储接口属于领域层；实现属于基础设施。 ## 来自整洁架构 * 向内依赖——领域永远不从基础设施或框架导入。 * 业务规则必须在没有 UI、数据库或外部服务的情况下可测试。 * 接口由用户拥有，而非实现者。 ## 来自 DDIA * 复制延迟是现实——在需要时围绕最终一致性设计 UX。 * 优先选择幂等操作用于重试。 * 当需要可审计性和重放时使用事件溯源。 * 区分偶然复杂性和本质复杂性——只对抗本质复杂性。

# awesome-claude-md — Curation Standards ## What This Repository Is A curated collection of exemplary CLAUDE.md files from public GitHub projects, with analysis and best practice templates. ## Quality Criteria for CLAUDE.md Files A high-quality CLAUDE.md should: **Essential (must have):** * Clear project context — what is this codebase, what language/framework * Build and test commands — copy-paste ready, no guessing * Key architectural decisions — explain non-obvious choices **Good to have:** * File structure overview for large projects * Common gotchas and known issues * Contribution workflow and conventions * Links to design docs or ADRs for major subsystems **Anti-patterns to avoid:** * Walls of text with no structure * Information that belongs in README, not CLAUDE.md * Over-specifying obvious things ("use good variable names") * Stale information that contradicts the actual codebase ## Scoring Rubric | Dimension | 0 — Missing | 1 — Partial | 2 — Complete | |-----------|-------------|-------------|--------------| | Context | No project description | Vague description | Clear + purpose | | Commands | No commands | Some commands | All commands work | | Architecture | No decisions | Some decisions | Key decisions documented | | Gotchas | None | 1-2 tips | Comprehensive | | Maintenance | Stale | Mostly current | Up to date | A score of 8/10 or above = exemplary. ## Curation Guidelines When adding a new CLAUDE.md to this collection: 1. Verify the file is from a public, maintained repository 2. Score it using the rubric above 3. Annotate what makes it notable 4. Categorize by primary use case (web, CLI, library, data, etc.)

# awesome-claude-md — 策展标准 ## 这个仓库是什么 来自公共 GitHub 项目的优秀 CLAUDE.md 文件精选集，附分析和最佳实践模板。 ## CLAUDE.md 文件的质量标准 高质量的 CLAUDE.md 应该： **必备（必须有）：** * 清晰的项目上下文——这是什么代码库，使用什么语言/框架 * 构建和测试命令——可直接复制粘贴，无需猜测 * 关键架构决策——解释非显而易见的选择 **最好有：** * 大型项目的文件结构概述 * 常见注意事项和已知问题 * 贡献工作流和约定 * 主要子系统的设计文档或 ADR 链接 **要避免的反模式：** * 没有结构的大段文字 * 属于 README 而非 CLAUDE.md 的信息 * 过度指定显而易见的事物（"使用好的变量名"） * 与实际代码库矛盾的过时信息 ## 评分标准 | 维度 | 0 — 缺失 | 1 — 部分 | 2 — 完整 | |------|---------|---------|---------| | 上下文 | 无项目描述 | 模糊描述 | 清晰 + 目的 | | 命令 | 无命令 | 部分命令 | 所有命令可用 | | 架构 | 无决策 | 部分决策 | 关键决策已记录 | | 注意事项 | 无 | 1-2 条提示 | 全面 | | 维护性 | 过时 | 大部分最新 | 最新 | 8/10 或以上 = 优秀。 ## 策展指南 向此集合添加新 CLAUDE.md 时： 1. 验证文件来自公共、维护中的仓库 2. 使用上述标准评分 3. 注释其值得关注的原因 4. 按主要用例分类（web、CLI、库、数据等）

# Claude Code Mastery — CLAUDE.md ## Hooks System Hooks let you run shell scripts at key Claude lifecycle events. Use them for automation, guardrails, and observability. ### Hook Events * `PreToolUse` — runs before any tool call; use exit code 2 to block * `PostToolUse` — runs after a tool completes; good for logging * `Stop` — runs when Claude finishes a response; good for notifications * `SubagentStart` / `SubagentStop` — fires for each subagent session * `UserPromptSubmit` — fires when user submits a message ### Exit Code Semantics | Code | Meaning | |------|---------| | 0 | Success — proceed normally | | 1 | Non-blocking warning — Claude sees the output | | 2 | Block the action — Claude cannot proceed | ### Example: Block Destructive Commands ```json { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{"type": "command", "command": "scripts/check-dangerous.sh"}] }] } } ``` ```bash #!/bin/bash # check-dangerous.sh if echo "$CLAUDE_TOOL_INPUT" | grep -qE '(rm -rf|DROP TABLE|DELETE FROM)'; then echo "Blocked: potentially destructive command detected" exit 2 fi exit 0 ``` ### Example: Auto-format on Edit ```bash # PostToolUse hook for Write/Edit tools #!/bin/bash FILE="$CLAUDE_TOOL_RESULT_path" if [[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then npx prettier --write "$FILE" fi ``` ## Memory System Best Practices Claude Code has 4 memory tiers: 1. `~/.claude/CLAUDE.md` — user-global instructions 2. `.claude/CLAUDE.md` — project-wide instructions 3. Subdirectory `CLAUDE.md` — component-specific 4. `/memory` command — session-scoped **Rule:** Put architectural decisions in project CLAUDE.md. Put component-specific patterns in subdirectory CLAUDE.md. Never put the same instruction in multiple levels — it creates contradictions. ## Slash Commands That Save Hours * `/compact` — compress context when approaching limit * `/review` — structured code review of current changes * `/doctor` — diagnose Claude Code configuration issues * `/memory` — view and edit the current memory state

# Claude Code 精通 — CLAUDE.md ## Hooks 系统 Hooks 让你在 Claude 生命周期的关键事件时运行 shell 脚本。用于自动化、护栏和可观测性。 ### Hook 事件 * `PreToolUse` — 在任何工具调用之前运行；使用退出码 2 来阻止 * `PostToolUse` — 工具完成后运行；适合日志记录 * `Stop` — Claude 完成响应时运行；适合通知 * `SubagentStart` / `SubagentStop` — 为每个 subagent 会话触发 * `UserPromptSubmit` — 用户提交消息时触发 ### 退出码语义 | 代码 | 含义 | |------|------| | 0 | 成功——正常继续 | | 1 | 非阻塞警告——Claude 看到输出 | | 2 | 阻止操作——Claude 无法继续 | ### 示例：阻止破坏性命令 ```bash #!/bin/bash # check-dangerous.sh if echo "$CLAUDE_TOOL_INPUT" | grep -qE '(rm -rf|DROP TABLE|DELETE FROM)'; then echo "已阻止：检测到可能具有破坏性的命令" exit 2 fi exit 0 ``` ### 示例：编辑时自动格式化 ```bash # Write/Edit 工具的 PostToolUse hook #!/bin/bash FILE="$CLAUDE_TOOL_RESULT_path" if [[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then npx prettier --write "$FILE" fi ``` ## 内存系统最佳实践 Claude Code 有 4 个内存层级： 1. `~/.claude/CLAUDE.md` — 用户全局指令 2. `.claude/CLAUDE.md` — 项目范围指令 3. 子目录 `CLAUDE.md` — 组件特定 4. `/memory` 命令 — 会话范围 **规则：** 将架构决策放在项目 CLAUDE.md 中。将组件特定模式放在子目录 CLAUDE.md 中。永远不要在多个层级中放置相同的指令——这会造成矛盾。 ## 节省数小时的斜杠命令 * `/compact` — 在接近限制时压缩上下文 * `/review` — 对当前更改进行结构化代码审查 * `/doctor` — 诊断 Claude Code 配置问题 * `/memory` — 查看和编辑当前内存状态

# Claude Code Best Practices — Multi-Agent Pipeline ## Agent Roster This project uses 10 specialized agents with explicit handoff protocols: | Agent | Responsibility | Inputs | Outputs | |-------|---------------|--------|---------| | `architect` | System design & ADRs | Requirements | Design doc | | `planner` | Sprint planning & task breakdown | Design doc | Task list | | `coder` | Implementation | Task + context | Code diff | | `tester` | Unit & integration tests | Code diff | Test suite | | `reviewer` | Code quality gate | Code diff + tests | Review report | | `security` | Vulnerability scan | Code diff | Security report | | `documenter` | Code docs & README | Final code | Documentation | | `integrator` | Merge & CI | All artifacts | PR | | `debugger` | Failure investigation | Error logs | Fix + explanation | | `optimizer` | Performance analysis | Profiling data | Optimization PR | ## Phase Gate Protocol Humans must approve before advancing between phases: ``` [REQUIREMENTS] → architect → [DESIGN REVIEW ✓] ↓ [DESIGN] → planner → [PLAN REVIEW ✓] ↓ [PLAN] → coder + tester (parallel) → [CODE REVIEW ✓] ↓ [CODE] → reviewer + security (parallel) → [QUALITY GATE ✓] ↓ [APPROVED] → documenter → integrator → [MERGED] ``` ## Handoff Contract Each agent must produce a structured handoff: ``` STATUS: [COMPLETE | BLOCKED | NEEDS_REVIEW] OUTPUTS: [list of files/artifacts produced] NEXT_AGENT: [who should receive this] NOTES: [anything the next agent needs to know] BLOCKERS: [anything that stopped completion] ``` ## Human Checkpoint Rules * Never advance past a phase gate without explicit human "LGTM" or equivalent * Blockers must surface to human — agents do not resolve ambiguity by themselves * Any deviation from the plan requires human approval before continuing

# Claude Code 最佳实践 — 多 Agent 流水线 ## Agent 名册 该项目使用 10 个专业化 agent，具有明确的交接协议： | Agent | 职责 | 输入 | 输出 | |-------|------|------|------| | `architect` | 系统设计和 ADR | 需求 | 设计文档 | | `planner` | Sprint 规划和任务分解 | 设计文档 | 任务列表 | | `coder` | 实现 | 任务 + 上下文 | 代码 diff | | `tester` | 单元和集成测试 | 代码 diff | 测试套件 | | `reviewer` | 代码质量门 | 代码 diff + 测试 | 审查报告 | | `security` | 漏洞扫描 | 代码 diff | 安全报告 | | `documenter` | 代码文档和 README | 最终代码 | 文档 | | `integrator` | 合并和 CI | 所有工件 | PR | | `debugger` | 故障调查 | 错误日志 | 修复 + 解释 | | `optimizer` | 性能分析 | 分析数据 | 优化 PR | ## 阶段门协议 人类必须在阶段间推进前批准： ``` [需求] → architect → [设计审查 ✓] ↓ [设计] → planner → [计划审查 ✓] ↓ [计划] → coder + tester（并行）→ [代码审查 ✓] ↓ [代码] → reviewer + security（并行）→ [质量门 ✓] ↓ [批准] → documenter → integrator → [合并] ``` ## 交接契约 每个 agent 必须产生结构化的交接： ``` STATUS: [COMPLETE | BLOCKED | NEEDS_REVIEW] OUTPUTS: [产生的文件/工件列表] NEXT_AGENT: [谁应该接收这个] NOTES: [下一个 agent 需要知道的任何事] BLOCKERS: [阻止完成的任何事] ``` ## 人工检查点规则 * 未经人类明确"LGTM"或等同意见，永远不要越过阶段门 * 阻碍必须上报给人类——agent 不自行解决歧义 * 任何偏离计划的行为在继续之前都需要人类批准

# claude-md-examples — Style Matching Guidelines ## The Invisible AI Principle The best AI-generated code is indistinguishable from code written by the team. Before writing anything, spend 5 minutes reading existing code in the relevant module. ## What to Read Before Writing 1. Look at 3 recent commits — what's the commit message style? 2. Read 2 files in the same module — what naming conventions are used? 3. Check the test file for a nearby feature — what's the testing style? 4. Scan package.json or pyproject.toml — what tooling is standard? ## Style Matching Checklist Before submitting any code: - [ ] Variable/function naming follows existing conventions (camelCase, snake_case, etc.) - [ ] Error handling matches project patterns (throws, Result types, callbacks, etc.) - [ ] Imports are organized in the project's way - [ ] Comments are in the project's language and style - [ ] Tests follow the same describe/it/test structure as existing tests - [ ] Logging uses the project's logger, not console.log - [ ] Async patterns match (async/await vs promises vs callbacks) ## Pattern Recognition Examples If you see existing code like: ```js const result = await db.query(sql, params).catch(handleDbError) ``` Don't write: ```js try { const result = await db.query(sql, params) } catch (e) { handleDbError(e) } ``` Even if both are correct — match the team's idiom. ## What Makes a Great CLAUDE.md From analyzing 200+ CLAUDE.md files: 1. **Context first**: What is this codebase? One paragraph max. 2. **Commands that work**: Build, test, lint — copy-paste ready 3. **The non-obvious**: What would confuse a new contributor? 4. **Keep it under 200 lines**: Longer = ignored

# claude-md-examples — 风格匹配指南 ## 隐形 AI 原则 最好的 AI 生成代码与团队编写的代码无法区分。在写任何东西之前，花 5 分钟阅读相关模块中的现有代码。 ## 写之前要读什么 1. 查看 3 个最近的提交——提交消息风格是什么？ 2. 阅读同一模块中的 2 个文件——使用了什么命名约定？ 3. 检查附近功能的测试文件——测试风格是什么？ 4. 扫描 package.json 或 pyproject.toml——什么工具是标准的？ ## 风格匹配清单 提交任何代码之前： - [ ] 变量/函数命名遵循现有约定（camelCase、snake_case 等） - [ ] 错误处理符合项目模式（抛出、Result 类型、回调等） - [ ] 导入以项目的方式组织 - [ ] 注释使用项目的语言和风格 - [ ] 测试遵循与现有测试相同的 describe/it/test 结构 - [ ] 日志使用项目的 logger，而不是 console.log - [ ] 异步模式匹配（async/await vs promises vs callbacks） ## 模式识别示例 如果你看到现有代码像这样： ```js const result = await db.query(sql, params).catch(handleDbError) ``` 不要写： ```js try { const result = await db.query(sql, params) } catch (e) { handleDbError(e) } ``` 即使两者都正确——匹配团队的惯用法。 ## 什么是优秀的 CLAUDE.md 分析 200+ 个 CLAUDE.md 文件： 1. **上下文优先**：这是什么代码库？最多一段。 2. **可用的命令**：构建、测试、lint——可直接复制粘贴 3. **非显而易见的内容**：什么会让新贡献者困惑？ 4. **保持在 200 行以内**：越长 = 越被忽略

# CLAUDE.md (rishabhsonker gist — viral version) ## Golden Rules (Read Every Time) 1. **MCP tools over bash, always.** If there's an MCP tool for it, use it. Don't grep when you can use the file tool. Don't curl when you can use fetch. Don't guess when you can read. 2. **Never, ever, EVER modify a test to make it pass.** If a test is failing, fix the code. The test is the contract. The test is truth. If you think the test is wrong, ask. 3. **Stop when blocked.** If you don't know something, say "I don't know" and stop. Don't hallucinate a solution. Don't make up an API. Ask. 4. **One change at a time.** Complete one task. Verify it. Then move on. Don't fix three things at once and call it done. ## Prohibited Actions The following are BANNED. No exceptions. No "but I think": - Modifying `.env` files - Deleting any file you didn't create in this session - Running `npm install` or `pip install` without confirming - Making API calls to external services - Committing directly to main/master - `console.log` in production code (use the project logger) ## Required Before Any PR - [ ] Run the full test suite and paste the output - [ ] Run the linter and paste the output - [ ] List every file you changed - [ ] Explain WHY each change was needed ## Tone I am paying attention. I will notice if you are hallucinating. I will notice if you are cutting corners. Be honest about uncertainty. Be explicit about tradeoffs. Be boring and correct rather than exciting and wrong.

# CLAUDE.md（rishabhsonker gist — 病毒传播版） ## 黄金法则（每次都要读） 1. **MCP 工具优先于 bash，永远如此。** 如果有 MCP 工具可用，就使用它。有文件工具时不要用 grep。有 fetch 工具时不要用 curl。能读到的时候不要猜。 2. **永远、永远、永远不要修改测试来让它通过。** 如果测试失败，修复代码。测试是契约。测试是真相。如果你认为测试是错的，问清楚。 3. **被阻塞时停下来。** 如果你不知道某事，说"我不知道"然后停下来。不要幻觉一个解决方案。不要编造一个 API。提问。 4. **一次一个改动。** 完成一个任务。验证它。然后继续。不要同时修三件事然后说完成了。 ## 禁止操作 以下是被禁止的。没有例外。没有"但我认为"： - 修改 `.env` 文件 - 删除本会话中你没有创建的任何文件 - 未确认运行 `npm install` 或 `pip install` - 向外部服务进行 API 调用 - 直接提交到 main/master - 生产代码中的 `console.log`（使用项目 logger） ## PR 之前必须做的 - [ ] 运行完整测试套件并粘贴输出 - [ ] 运行 linter 并粘贴输出 - [ ] 列出你更改的每个文件 - [ ] 解释为什么需要每个改动 ## 语气 我在关注。如果你在幻觉，我会注意到。如果你在走捷径，我会注意到。对不确定性要诚实。对权衡要明确。宁可无聊但正确，也不要激动人心但错误。