everything-claude-code-conventions

Everything Claude Code Conventions

Generated from affaan-m/everything-claude-code on 2026-03-20

總覽

本 Skill 旨在協助 Claude 掌握 everything-claude-code 所採用的開發模式與規範。

技術堆疊

• 主要語言：JavaScript
• 架構：混合式模組組織（hybrid module organization）
• 測試檔案位置：獨立存放

何時使用此 Skill

在以下時機啟用此 Skill：

• 修改此儲存庫時
• 遵循既有模式新增功能時
• 撰寫符合專案規範的測試時
• 建立符合正確格式的 commit 訊息時

Commit 規範

以下為分析 500 個 commit 後整理出的 commit 訊息規範。

Commit 風格：Conventional Commits

使用的前綴

• fix
• test
• feat
• docs

訊息撰寫指南

• 平均訊息長度：約 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

Import 風格：相對路徑引入（Relative Imports）

Export 風格：混合風格（Mixed Style）

建議的 Import 風格

// Use relative imports
import { Button } from '../components/Button'
import { useAuth } from './hooks/useAuth'

測試

測試框架

未偵測到特定的測試框架 — 請使用儲存庫既有的測試模式。

檔案命名模式：*.test.js

測試類型

• 單元測試：獨立測試個別函式與元件
• 整合測試：測試多個元件/服務之間的互動

覆蓋率

本專案已設定測試覆蓋率報告，目標達到 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）

透過 migration 檔案進行資料庫 schema 變更

頻率：每月約 2 次

步驟：

1. 建立 migration 檔案
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)

功能開發

標準功能實作工作流程

頻率：每月約 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

新增語言規則

在規則系統中新增程式語言，包含程式碼風格、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

將新的 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

將新的 agent 新增至系統中，用於 code review、建置問題排除或其它自動化任務。

頻率：每月約 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

將新的 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

同步目錄統計數量

將 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 的 Skill 副本

為不同的 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

新增或更新 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 回饋

藉由更新文件、指令碼或設定檔來處理 Code Review 回饋，提升清晰度、正確性或符合團隊規範。

頻率：每月約 4 次

步驟：

1. 編輯 SKILL.md、agent 或 command 檔案以回應 Reviewer 的意見
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

最佳實踐

根據程式碼庫的分析結果，請遵循以下最佳做法：

建議的做法

• 使用 Conventional Commits 格式（如 feat:、fix: 等）
• 遵循 *.test.js 的命名模式
• 檔名使用 camelCase
• 優先使用混合導出（mixed exports）

應避免的做法

• 避免撰寫含糊不清的 commit 訊息
• 新增功能時請勿跳過測試
• 未經討論請勿偏離既有的開發模式

---

此 Skill 由 ECC Tools 自動產生。請根據團隊需求進行審閱與自訂。