everything-claude-code/docs/zh-CN/AGENTS.md

Everything Claude Code (ECC) — 智能体指令

这是一个生产就绪的 AI 编码插件，提供 16 个专业代理、65+ 项技能、40 条命令以及自动化钩子工作流，用于软件开发。

核心原则

1. 智能体优先 — 将领域任务委托给专业智能体
2. 测试驱动 — 先写测试再实现，要求 80%+ 覆盖率
3. 安全第一 — 绝不妥协安全；验证所有输入
4. 不可变性 — 总是创建新对象，永不修改现有对象
5. 先规划后执行 — 在编写代码前规划复杂功能

可用智能体

代理	用途	使用时机
planner	实施规划	复杂功能、重构
architect	系统设计与可扩展性	架构决策
tdd-guide	测试驱动开发	新功能、错误修复
code-reviewer	代码质量与可维护性	编写/修改代码后
security-reviewer	漏洞检测	提交前、敏感代码
build-error-resolver	修复构建/类型错误	构建失败时
e2e-runner	端到端 Playwright 测试	关键用户流程
refactor-cleaner	死代码清理	代码维护
doc-updater	文档与代码映射更新	更新文档时
go-reviewer	Go 代码审查	Go 项目
go-build-resolver	Go 构建错误	Go 构建失败时
database-reviewer	PostgreSQL/Supabase 专家	模式设计、查询优化
python-reviewer	Python 代码审查	Python 项目
chief-of-staff	沟通分流与草稿	多渠道电子邮件、Slack、LINE、Messenger
loop-operator	自主循环执行	安全运行循环、监控停滞、干预
harness-optimizer	线束配置调优	可靠性、成本、吞吐量

智能体编排

主动使用智能体，无需用户提示：

• 复杂功能请求 → planner
• 刚编写/修改的代码 → code-reviewer
• 错误修复或新功能 → tdd-guide
• 架构决策 → architect
• 安全敏感代码 → security-reviewer
• 多渠道沟通分流 → chief-of-staff
• 自主循环 / 循环监控 → loop-operator
• 线束配置可靠性及成本 → harness-optimizer

对于独立操作使用并行执行 — 同时启动多个智能体。

安全指南

在任何提交之前：

• 没有硬编码的密钥（API 密钥、密码、令牌）
• 所有用户输入都经过验证
• 防止 SQL 注入（参数化查询）
• 防止 XSS（已清理的 HTML）
• 启用 CSRF 保护
• 已验证身份验证/授权
• 所有端点都有限速
• 错误消息不泄露敏感数据

密钥管理： 绝不硬编码密钥。使用环境变量或密钥管理器。在启动时验证所需的密钥。立即轮换任何暴露的密钥。

如果发现安全问题： 停止 → 使用 security-reviewer 智能体 → 修复 CRITICAL 问题 → 轮换暴露的密钥 → 审查代码库中的类似问题。

编码风格

不可变性（关键）： 总是创建新对象，永不修改。返回带有更改的新副本。

文件组织： 许多小文件优于少数大文件。通常 200-400 行，最多 800 行。按功能/领域组织，而不是按类型组织。高内聚，低耦合。

错误处理： 在每个层级处理错误。在 UI 代码中提供用户友好的消息。在服务器端记录详细的上下文。绝不静默地忽略错误。

输入验证： 在系统边界验证所有用户输入。使用基于模式的验证。快速失败并给出清晰的消息。绝不信任外部数据。

代码质量检查清单：

• 函数小巧（<50 行），文件专注（<800 行）
• 没有深层嵌套（>4 层）
• 适当的错误处理，没有硬编码的值
• 可读性强、命名良好的标识符

测试要求

最低覆盖率：80%

测试类型（全部必需）：

1. 单元测试 — 单个函数、工具、组件
2. 集成测试 — API 端点、数据库操作
3. 端到端测试 — 关键用户流程

TDD 工作流（强制）：

1. 先写测试（RED） — 测试应该失败
2. 编写最小实现（GREEN） — 测试应该通过
3. 重构（IMPROVE） — 验证覆盖率 80%+

故障排除：检查测试隔离 → 验证模拟 → 修复实现（而不是测试，除非测试是错误的）。

开发工作流

1. 规划 — 使用规划代理，识别依赖关系和风险，分阶段推进
2. 测试驱动开发 — 使用 tdd-guide 代理，先写测试，再实现和重构
3. 评审 — 立即使用代码评审代理，解决 CRITICAL/HIGH 级别的问题
4. 在适当位置记录知识
   • 个人调试笔记、偏好和临时上下文 → 自动记忆
   • 团队/项目知识（架构决策、API 变更、操作手册）→ 项目现有文档结构
   • 如果当前任务已生成相关文档或代码注释，请勿在其他地方重复相同信息
   • 如果没有明显的项目文档位置，在创建新的顶层文件前先询问
5. 提交 — 采用约定式提交格式，提供全面的 PR 摘要

Git 工作流

提交格式： <type>: <description> — 类型：feat, fix, refactor, docs, test, chore, perf, ci

PR 工作流： 分析完整的提交历史 → 起草全面的摘要 → 包含测试计划 → 使用 -u 标志推送。

架构模式

API 响应格式： 具有成功指示器、数据负载、错误消息和分页元数据的一致信封。

仓储模式： 将数据访问封装在标准接口（findAll, findById, create, update, delete）后面。业务逻辑依赖于抽象接口，而不是存储机制。

骨架项目： 搜索经过实战检验的模板，使用并行智能体（安全性、可扩展性、相关性）进行评估，克隆最佳匹配，在已验证的结构内迭代。

性能

上下文管理： 对于大型重构和多文件功能，避免使用上下文窗口的最后 20%。敏感性较低的任务（单次编辑、文档、简单修复）可以容忍较高的利用率。

构建故障排除： 使用 build-error-resolver 智能体 → 分析错误 → 增量修复 → 每次修复后验证。

项目结构

agents/          — 13 specialized subagents
skills/          — 65+ workflow skills and domain knowledge
commands/        — 40 slash commands
hooks/           — Trigger-based automations
rules/           — Always-follow guidelines (common + per-language)
scripts/         — Cross-platform Node.js utilities
mcp-configs/     — 14 MCP server configurations
tests/           — Test suite

成功指标

• 所有测试通过且覆盖率 80%+
• 没有安全漏洞
• 代码可读且可维护
• 性能可接受
• 满足用户需求