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

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

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

版本: 1.9.0

核心原则

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

可用智能体

代理	用途	使用时机
planner	实现规划	复杂功能、重构
architect	系统设计与可扩展性	架构决策
tdd-guide	测试驱动开发	新功能、错误修复
code-reviewer	代码质量与可维护性	编写/修改代码后
security-reviewer	漏洞检测	提交前、敏感代码
build-error-resolver	修复构建/类型错误	构建失败时
e2e-runner	端到端 Playwright 测试	关键用户流程
refactor-cleaner	死代码清理	代码维护
doc-updater	文档和代码地图更新	更新文档时
docs-lookup	文档和 API 参考研究	库/API 文档问题
cpp-reviewer	C++ 代码审查	C++ 项目
cpp-build-resolver	C++ 构建错误	C++ 构建失败
go-reviewer	Go 代码审查	Go 项目
go-build-resolver	Go 构建错误	Go 构建失败
kotlin-reviewer	Kotlin 代码审查	Kotlin/Android/KMP 项目
kotlin-build-resolver	Kotlin/Gradle 构建错误	Kotlin 构建失败
database-reviewer	PostgreSQL/Supabase 专家	模式设计、查询优化
python-reviewer	Python 代码审查	Python 项目
java-reviewer	Java 和 Spring Boot 代码审查	Java/Spring Boot 项目
java-build-resolver	Java/Maven/Gradle 构建错误	Java 构建失败
chief-of-staff	沟通分类与草拟	多渠道邮件、Slack、LINE、Messenger
loop-operator	自主循环执行	安全运行循环、监控停滞、干预
harness-optimizer	Harness 配置调优	可靠性、成本、吞吐量
rust-reviewer	Rust 代码审查	Rust 项目
rust-build-resolver	Rust 构建错误	Rust 构建失败
pytorch-build-resolver	PyTorch 运行时/CUDA/训练错误	PyTorch 构建/训练失败
typescript-reviewer	TypeScript/JavaScript 代码审查	TypeScript/JavaScript 项目

智能体编排

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

• 复杂功能请求 → 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/          — 28 个专业子代理
skills/          — 115 个工作流技能和领域知识
commands/        — 59 个斜杠命令
hooks/           — 基于触发的自动化
rules/           — 始终遵循的指导方针（通用 + 每种语言）
scripts/         — 跨平台 Node.js 实用工具
mcp-configs/     — 14 个 MCP 服务器配置
tests/           — 测试套件

成功指标

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