everything-claude-code-conventions

Everything Claude Code 规范指南

生成自 affaan-m/everything-claude-code（生成时间：2026-03-20）

项目概览

本 Skill 旨在让 Claude 掌握 everything-claude-code 项目中使用的开发模式与约定规范。

技术栈

• 主语言：JavaScript
• 架构：混合模块组织模式（hybrid module organization）
• 测试代码路径：独立放置（separate）

何时使用本 Skill

在以下场景下触发/激活本 Skill：

• 对本仓库进行代码变更时
• 遵循既有模式添加新功能时
• 编写符合项目规范的测试用例时
• 按照标准格式提交 Commit 时

Commit 提交规范

基于分析的 500 次 Commit 总结出的提交信息规范。

Commit 风格：Conventional Commits

常用前缀

• fix
• test
• feat
• docs

Commit 信息要求

• 平均长度：约 65 个字符
• 首行保持简洁明了、直击重点
• 使用祈使句式（用 "Add feature" 而非 "Added feature"）

Commit 信息示例

feat(rules): add C# language support

Commit 信息示例

chore(deps-dev): bump flatted (#675)

Commit 信息示例

fix: auto-detect ECC root from plugin cache when CLAUDE_PLUGIN_ROOT is unset (#547) (#691)

Commit 信息示例

docs: add Antigravity setup and usage guide (#552)

Commit 信息示例

merge: PR #529 — feat(skills): add documentation-lookup, bun-runtime, nextjs-turbopack; feat(agents): add rust-reviewer

Commit 信息示例

Revert "Add Kiro IDE support (.kiro/) (#548)"

Commit 信息示例

Add Kiro IDE support (.kiro/) (#548)

Commit 信息示例

feat: add block-no-verify hook for Claude Code and Cursor (#649)

项目架构

项目结构：单包模式（Single Package）

本项目采用 混合（hybrid） 模块组织方式。

配置文件

• .github/workflows/ci.yml
• .github/workflows/maintenance.yml
• .github/workflows/monthly-metrics.yml
• .github/workflows/release.yml
• .github/workflows/reusable-release.yml
• .github/workflows/reusable-test.yml
• .github/workflows/reusable-validate.yml
• .opencode/package.json
• .opencode/tsconfig.json
• .prettierrc
• eslint.config.js
• package.json

开发指南

• 本项目采用混合组织结构
• 新增代码时请遵循现有的代码模式

代码风格

开发语言：JavaScript

命名规范

元素	规范
文件	camelCase
函数	camelCase
类	PascalCase
常量	SCREAMING_SNAKE_CASE

导入风格：相对路径导入（Relative Imports）

导出风格：混合导出（Mixed Style）

推荐的导入风格

// 使用相对路径导入
import { Button } from '../components/Button'
import { useAuth } from './hooks/useAuth'

自动化测试

测试框架

未检测到特定的测试框架 — 请直接遵循仓库中已有的测试模式。

文件匹配规则：*.test.js

测试类型

• 单元测试（Unit tests）：独立测试单个函数和组件
• 集成测试（Integration tests）：测试多个组件/服务之间的协作交互

覆盖率

本项目已配置测试覆盖率报告，目标覆盖率要求达到 80%+。

错误处理

错误处理风格：Try-Catch 语句块

标准错误处理模式

try {
  const result = await riskyOperation()
  return result
} catch (error) {
  console.error('Operation failed:', error)
  throw new Error('User-friendly message')
}

常见工作流

以下工作流系通过分析仓库 Commit 历史记录自动检测得出。

数据库迁移（Database Migration）

配合迁移文件对数据库 Schema 进行变更

触发频率：约每月 2 次

具体步骤：

1. 创建迁移文件
2. 更新 Schema 定义
3. 生成/更新类型定义

主要涉及文件：

• **/schema.*
• migrations/*

Commit 历史示例：

feat: implement --with/--without selective install flags (#679)
fix: sync catalog counts with filesystem (27 agents, 113 skills, 58 commands) (#693)
feat(rules): add Rust language rules (rebased #660) (#686)

功能开发（Feature Development）

标准功能开发与实现流程

触发频率：约每月 22 次

具体步骤：

1. 编写功能实现代码
2. 添加对应的测试用例
3. 更新相关文档

主要涉及文件：

• manifests/*
• schemas/*
• **/*.test.*
• **/api/**

Commit 历史示例：

feat(skills): add documentation-lookup, bun-runtime, nextjs-turbopack; feat(agents): add rust-reviewer
docs(skills): align documentation-lookup with CONTRIBUTING template; add cross-harness (Codex/Cursor) skill copies
fix: address PR review — skill template (When to use, How it works, Examples), bun.lock, next build note, rust-reviewer CI note, doc-lookup privacy/uncertainty

添加语言规则（Add Language Rules）

为规则系统添加新的编程语言支持，包括代码风格、Hooks、设计模式、安全规范及测试指南。

触发频率：约每月 2 次

具体步骤：

1. 在 rules/{language}/ 下新建目录
2. 添加 coding-style.md、hooks.md、patterns.md、security.md 和 testing.md 文件并写入对应语言的内容
3. （可选）关联或链接到相关的 Skill

主要涉及文件：

• rules/*/coding-style.md
• rules/*/hooks.md
• rules/*/patterns.md
• rules/*/security.md
• rules/*/testing.md

Commit 历史示例：

Create a new directory under rules/{language}/
Add coding-style.md, hooks.md, patterns.md, security.md, and testing.md files with language-specific content
Optionally reference or link to related skills

新增 Skill（Add New Skill）

向系统添加新 Skill，记录其工作流、触发条件及使用说明，通常附带支持脚本。

触发频率：约每月 4 次

具体步骤：

1. 在 skills/{skill-name}/ 下新建目录
2. 添加包含文档说明的 SKILL.md（包含使用场景、运行机制、代码示例等）
3. （可选）在 skills/{skill-name}/scripts/ 下添加脚本或配套文件
4. 根据 Review 反馈进行文档迭代修改

主要涉及文件：

• skills/*/SKILL.md
• skills/*/scripts/*.sh
• skills/*/scripts/*.js

Commit 历史示例：

Create a new directory under skills/{skill-name}/
Add SKILL.md with documentation (When to Use, How It Works, Examples, etc.)
Optionally add scripts or supporting files under skills/{skill-name}/scripts/
Address review feedback and iterate on documentation

新增 Agent（Add New Agent）

向系统添加新的 Agent，用于代码审查、构建问题排查或其他自动化任务。

触发频率：约每月 2 次

具体步骤：

1. 在 agents/{agent-name}.md 创建新的 Agent Markdown 文件
2. 在 AGENTS.md 中注册该 Agent
3. （可选）更新 README.md 和 docs/COMMAND-AGENT-MAP.md

主要涉及文件：

• agents/*.md
• AGENTS.md
• README.md
• docs/COMMAND-AGENT-MAP.md

Commit 历史示例：

Create a new agent markdown file under agents/{agent-name}.md
Register the agent in AGENTS.md
Optionally update README.md and docs/COMMAND-AGENT-MAP.md

新增 Command 命令（Add New Command）

向系统添加新的 Command 命令，通常会配合底层 Skill 一起使用。

触发频率：约每月 1 次

具体步骤：

1. 在 commands/{command-name}.md 下创建新的 Markdown 文件
2. （可选）在 skills/{skill-name}/SKILL.md 中添加或更新支撑该命令的 Skill

主要涉及文件：

• commands/*.md
• skills/*/SKILL.md

Commit 历史示例：

Create a new markdown file under commands/{command-name}.md
Optionally add or update a backing skill under skills/{skill-name}/SKILL.md

同步 Catalog 计数（Sync Catalog Counts）

将 AGENTS.md 和 README.md 中记录的 Agent、Skill 及 Command 数量与仓库实际状态保持一致。

触发频率：约每月 3 次

具体步骤：

1. 更新 AGENTS.md 中的 Agent、Skill 和 Command 数量
2. 同步更新 README.md 中的数量（快速上手、对比表格等位置）
3. （可选）更新其他文档文件

主要涉及文件：

• AGENTS.md
• README.md

Commit 历史示例：

Update agent, skill, and command counts in AGENTS.md
Update the same counts in README.md (quick-start, comparison table, etc.)
Optionally update other documentation files

跨平台 Harness 副本同步（Add Cross Harness Skill Copies）

针对不同的 Agent Harness（如 Codex、Cursor、Antigravity）复制 Skill 副本，确保跨平台兼容性。

触发频率：约每月 2 次

具体步骤：

1. 将 SKILL.md 复制或适配到 .agents/skills/{skill}/SKILL.md 和/或 .cursor/skills/{skill}/SKILL.md
2. （可选）添加特定 Harness 所需的 openai.yaml 或配置文件
3. 根据 Review 反馈进行调整，使其对齐 CONTRIBUTING 模板规范

主要涉及文件：

• .agents/skills/*/SKILL.md
• .cursor/skills/*/SKILL.md
• .agents/skills/*/agents/openai.yaml

Commit 历史示例：

Copy or adapt SKILL.md to .agents/skills/{skill}/SKILL.md and/or .cursor/skills/{skill}/SKILL.md
Optionally add harness-specific openai.yaml or config files
Address review feedback to align with CONTRIBUTING template

添加或更新 Hook（Add Or Update Hook）

新增或更新 Git / Bash Hook 脚本，用于规范工作流、质量管控或安全策略。

触发频率：约每月 1 次

具体步骤：

1. 在 hooks/ 或 scripts/hooks/ 中添加或更新 Hook 脚本
2. 在 hooks/hooks.json 或类似配置文件中注册该 Hook
3. （可选）在 tests/hooks/ 下添加或更新测试用例

主要涉及文件：

• hooks/*.hook
• hooks/hooks.json
• scripts/hooks/*.js
• tests/hooks/*.test.js
• .cursor/hooks.json

Commit 历史示例：

Add or update hook scripts in hooks/ or scripts/hooks/
Register the hook in hooks/hooks.json or similar config
Optionally add or update tests in tests/hooks/

处理 Review 反馈（Address Review Feedback）

通过修改文档、脚本或配置，响应 Code Review 反馈，以确保代码的清晰度、准确性与规范一致性。

触发频率：约每月 4 次

具体步骤：

1. 修改 SKILL.md、Agent 或 Command 文件，回应评审人的意见
2. 按要求更新示例、标题或配置
3. 持续迭代直至解决所有 Review 反馈

主要涉及文件：

• skills/*/SKILL.md
• agents/*.md
• commands/*.md
• .agents/skills/*/SKILL.md
• .cursor/skills/*/SKILL.md

Commit 历史示例：

Edit SKILL.md, agent, or command files to address reviewer comments
Update examples, headings, or configuration as requested
Iterate until all review feedback is resolved

最佳实践

结合项目代码库的分析，建议遵循以下实践要求：

推荐做法（Do）

• 规范使用 Conventional Commits 提交格式（feat:、fix: 等）
• 遵循 *.test.js 的文件命名规则
• 文件名采用 camelCase 命名
• 优先选择混合导出（mixed exports）

避坑指南（Don't）

• 不要写含糊不清的 Commit message
• 新功能切勿漏写测试代码
• 未经讨论，不要擅自脱离已建立的规范模式

---

本 Skill 由 ECC Tools 自动生成。请根据团队实际需求审阅并调整。