Claude Code 项目配置展示

大多数软件工程师都严重低估了当前大语言模型代理的强大能力，尤其是像 Claude Code 这样的工具。

一旦你完成了 Claude Code 的设置，就可以让它指向你的代码库，学习你的编码规范，引入最佳实践，并不断优化，直到它几乎像一个功能超强的团队成员一样工作。真正的关键在于构建一套坚实的可复用“技能”以及几个针对你日常任务的“代理”。

实际应用示例

自定义 UI 库？ 我们有一个技能专门讲解如何使用它。同样地，关于我们如何编写测试、GraphQL 的结构化方式，以及基本上我们在仓库中希望完成所有事情的方式，都有相应的技能文档。因此，当 Claude 生成代码时，它已经能够直接符合我们的模式和标准。

自动化质量门控？ 我们使用钩子来自动格式化代码、在测试文件变更时运行测试、进行 TypeScript 类型检查，甚至阻止对主分支的编辑。Claude Code 还创建了一系列 ESLint 自动化规则，包括自定义规则和 lint 检查，能够在代码进入评审之前就捕获问题。

深度代码审查？ 我们有一个代码审查代理，Claude 会在代码变更后运行它。该代理会遵循一份详细的检查清单，涵盖 TypeScript 的严格模式、错误处理、加载状态、数据变更模式等。当 PR 提交时，我们还有一个GitHub Action，可以自动完成整个 PR 审查流程。

定期维护？ 我们设置了按计划运行的 GitHub 工作流代理：

• 每月文档同步：读取过去一个月的提交记录，确保文档仍然保持一致。
• 每周代码质量检查：随机审查目录并自动修复问题。
• 每两周依赖项审计：在测试验证通过的情况下安全更新依赖项。

智能技能建议？ 我们构建了一个技能评估系统，它可以分析每一个提示，并根据关键词、文件路径和意图模式自动建议 Claude 应该激活哪些技能。

大量的维护和质量相关工作都已经实现了自动化，运行得非常顺畅。

JIRA/Linear 集成？ 我们通过MCP 服务器将 Claude Code 与我们的工单系统连接起来。现在，Claude 可以读取工单、理解需求、实现功能、更新工单状态，甚至在发现 bug 时创建新的工单。[/ticket] 命令](.claude/commands/ticket.md) 能够处理整个工作流程——从阅读验收条件到将 PR 关联回工单。

我们甚至用 Claude Code 来进行工单分类。它会读取工单内容，深入研究代码库，并留下评论说明它认为应该怎么做。这样，当工程师接手时，实际上已经完成了大约一半的工作。

这里有太多唾手可得的机会，说实话，我简直不敢相信竟然还有人没有充分利用它们。

---

目录

• 目录结构
• 快速入门
• 配置参考
  • CLAUDE.md — 项目记忆
  • settings.json — 钩子与环境
  • MCP 服务器 — 外部集成
  • LSP 服务器 — 实时代码智能
  • 技能评估钩子
  • 技能 — 领域知识
  • 代理 — 专业助手
  • 命令 — 斜杠命令
• GitHub Actions 工作流
• 最佳实践
• 本仓库中的示例

---

目录结构

your-project/
├── CLAUDE.md                      # 项目记忆（备选位置）
├── .mcp.json                      # MCP 服务器配置（JIRA、GitHub 等）
├── .claude/
│   ├── settings.json              # 钩子、环境、权限
│   ├── settings.local.json        # 个人覆盖配置（已忽略在 Git 中）
│   ├── settings.md                # 人类可读的钩子文档
│   ├── .gitignore                 # 忽略本地/个人文件
│   │
│   ├── agents/                    # 自定义 AI 代理
│   │   └── code-reviewer.md       # 主动式代码审查代理
│   │
│   ├── commands/                  # 斜杠命令（/command-name）
│   │   ├── onboard.md             # 深度任务探索
│   │   ├── pr-review.md           # PR 审查工作流
│   │   └── ...
│   │
│   ├── hooks/                     # 钩子脚本
│   │   ├── skill-eval.sh          # 在提交提示时匹配技能
│   │   ├── skill-eval.js          # Node.js 技能匹配引擎
│   │   └── skill-rules.json       # 模式匹配配置
│   │
│   ├── skills/                    # 领域知识文档
│   │   ├── README.md              # 技能概述
│   │   ├── testing-patterns/
│   │   │   └── SKILL.md
│   │   ├── graphql-schema/
│   │   │   └── SKILL.md
│   │   └── ...
│   │
│   └── rules/                     # 模块化指令（可选）
│       ├── code-style.md
│       └── security.md
│
└── .github/
    └── workflows/
        ├── pr-claude-code-review.yml           # 自动 PR 审查
        ├── scheduled-claude-code-docs-sync.yml # 每月文档同步
        ├── scheduled-claude-code-quality.yml   # 每周质量审查
        └── scheduled-claude-code-dependency-audit.yml

---

快速入门

1. 创建 .claude 目录

mkdir -p .claude/{agents,commands,hooks,skills}

2. 添加 CLAUDE.md 文件

在项目根目录下创建 CLAUDE.md，填写项目的关键信息。完整的示例请参阅 CLAUDE.md。

# 项目名称

## 快速信息
- **技术栈**: React、TypeScript、Node.js
- **测试命令**: `npm run test`
- **Lint 命令**: `npm run lint`

## 关键目录
- `src/components/` — React 组件
- `src/api/` — API 层
- `tests/` — 测试文件

## 代码风格
- 使用 TypeScript 严格模式
- 优先使用接口而非类型
- 不使用 `any`，改用 `unknown`

3. 添加带有钩子的 settings.json

创建 .claude/settings.json。完整示例请参见 settings.json，其中包含自动格式化、测试等功能。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

4. 添加你的第一个技能

创建 .claude/skills/testing-patterns/SKILL.md。全面示例请参见 testing-patterns/SKILL.md。

---
name: testing-patterns
description: Jest 测试模式，适用于该项目。在编写测试、创建模拟对象或遵循 TDD 工作流程时使用。
---

# 测试模式

## 测试结构
- 使用 `describe` 块进行分组
- 使用 `it` 进行单个测试
- 遵循 AAA 模式：安排、行动、断言

## 模拟
- 使用工厂函数：`getMockUser(overrides)`
- 模拟外部依赖项，而非内部模块

提示: description 字段至关重要——Claude 会根据它来决定何时应用该技能。请包含用户自然会提到的关键字。

---

配置参考

CLAUDE.md - 项目记忆

CLAUDE.md 是 Claude 的持久化记忆，在会话开始时会自动加载。

位置（按优先级顺序）：

1. .claude/CLAUDE.md（项目级，位于 .claude 文件夹中）
2. ./CLAUDE.md（项目根目录）
3. ~/.claude/CLAUDE.md（用户级，适用于所有项目）

应包含的内容：

• 项目技术栈和架构概述
• 关键命令（测试、构建、 lint、部署）
• 代码风格指南
• 重要目录及其用途
• 重要规则和约束

📄 示例: CLAUDE.md

---

settings.json - 钩子与环境

这是用于配置钩子、环境变量和权限的主要配置文件。

位置: .claude/settings.json

📄 示例: settings.json | 人类可读文档

钩子事件

事件	触发时机	使用场景
PreToolUse	在工具执行之前	阻止在主分支上编辑，验证命令
PostToolUse	在工具执行完毕后	自动格式化，运行测试，执行 lint
UserPromptSubmit	用户提交提示时	添加上下文，建议技能
Stop	代理结束时	决定 Claude 是否应继续

钩子响应格式

{
  "block": true,           // 阻止操作（仅限 PreToolUse）
  "message": "原因",     // 向用户显示的消息
  "feedback": "信息",      // 非阻塞反馈
  "suppressOutput": true,  // 隐藏命令输出
  "continue": false        // 是否继续
}

退出码

• 0 - 成功
• 2 - 阻塞型错误（仅限 PreToolUse，会阻止工具执行）
• 其他 - 非阻塞型错误

---

MCP 服务器 - 外部集成

MCP（模型上下文协议）服务器使 Claude Code 能够连接到 JIRA、GitHub、Slack、数据库等外部工具。通过这种方式，您可以实现诸如“读取工单、执行开发并更新工单状态”之类的自动化工作流。

位置： .mcp.json 文件（项目根目录，已提交至 Git 以便团队共享）

📄 示例： .mcp.json

MCP 的工作原理

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│   MCP 服务器    │────▶│  外部 API       │
│                 │◀────│  (本地桥接)      │◀────│  (JIRA、GitHub) │
└─────────────────┘     └─────────────────┘     └─────────────────┘

MCP 服务器在本地运行，为 Claude 提供与外部服务交互的工具。例如，当您配置一个 JIRA 的 MCP 服务器时，Claude 就会获得 jira_get_issue、jira_update_issue、jira_create_issue 等工具。

.mcp.json 格式

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

字段说明：

字段	必需	描述
type	是	服务器类型：stdio（本地进程）或 http（远程）
command	是	要执行的命令行工具（如 npx、python）
args	否	命令行参数
env	否	环境变量（支持 ${VAR} 扩展）
url	否	远程服务器 URL
headers	否	用于身份验证的 HTTP 头

示例：JIRA 集成

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-jira"],
      "env": {
        "JIRA_HOST": "${JIRA_HOST}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

启用的功能：

• 读取工单详情、验收标准和评论
• 更新工单状态（待办 → 进行中 → 审核中）
• 添加进度更新评论
• 在开发过程中发现的 bug 创建新工单
• 将 PR 与工单关联

使用 /ticket 命令 的示例工作流：

您：/ticket PROJ-123

Claude：
1. 从 JIRA 获取 PROJ-123...
   “添加用户个人资料头像上传”

2. 阅读验收标准...
   - 个人资料页面上的上传按钮
   - 支持 JPG/PNG 格式，最大 5MB
   - 显示加载状态

3. 搜索代码库中相关文件...
   找到：src/screens/Profile/ProfileScreen.tsx

4. 创建分支：cw/PROJ-123-avatar-upload

5. [实现功能...]

6. 将 JIRA 状态更新为“审核中”
   添加评论：“PR #456 已准备好审核”

7. 创建与 PROJ-123 关联的 PR...

常见的 MCP 服务器配置

问题跟踪：

{
  "jira": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-jira"],
    "env": {
      "JIRA_HOST": "${JIRA_HOST}",
      "JIRA_EMAIL": "${JIRA_EMAIL}",
      "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
    }
  },
  "linear": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-linear"],
    "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
  }
}

代码与 DevOps：

{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-github"],
    "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
  },
  "sentry": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-sentry"],
    "env": {
      "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
      "SENTRY_ORG": "${SENTRY_ORG}"
    }
  }
}

沟通工具：

{
  "slack": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
    }
  }
}

数据库：

{
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-postgres"],
    "env": { "DATABASE_URL": "${DATABASE_URL}" }
  }
}

环境变量

MCP 配置支持变量扩展：

• ${VAR} - 展开为环境变量（未设置则失败）
• ${VAR:-default} - 如果 VAR 未设置，则使用默认值

请在您的 shell 配置文件或 .env 文件中设置这些变量（切勿提交敏感信息！）：

export JIRA_HOST="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="your-api-token"

MCP 相关设置

在 settings.json 中，您可以自动批准所有 MCP 服务器：

{
  "enableAllProjectMcpServers": true
}

或者仅批准特定的服务器：

{
  "enabledMcpjsonServers": ["jira", "github", "slack"]
}

---

LSP 服务器 - 实时代码智能

LSP（语言服务器协议）为 Claude 提供了对您代码的实时理解——包括类型信息、错误提示、代码补全和导航功能。与仅仅阅读文本不同，Claude 可以像您的 IDE 一样“看到”您的代码。

重要性： 当您编辑 TypeScript 代码时，Claude 会立即检测到是否引入了类型错误。当您引用某个函数时，Claude 可以直接跳转到该函数的定义处。这极大地提升了代码生成的质量。

启用 LSP

LSP 支持通过 settings.json 中的插件来启用：

{
  "enabledPlugins": {
    "typescript-lsp@claude-plugins-official": true,
    "pyright-lsp@claude-plugins-official": true
  }
}

Claude 从 LSP 获得的功能

功能	描述
诊断信息	每次编辑后实时显示错误和警告
类型信息	鼠标悬停时显示函数签名、类型定义等
代码导航	跳转到定义、查找引用
代码补全	根据上下文提供符号建议

可用的 LSP 插件

插件	语言	是否需要先安装二进制文件
typescript-lsp	TypeScript/JavaScript	是
pyright-lsp	Python	是
rust-lsp	Rust	是

自定义 LSP 配置

对于高级设置，可以创建 .lsp.json 文件：

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact"
    },
    "initializationOptions": {
      "preferences": {
        "quotePreference": "single"
      }
    }
  }
}

故障排除

如果 LSP 无法正常工作：

1. 检查二进制文件是否已安装：

   which typescript-language-server  # 应返回路径
   

2. 启用调试日志：

   claude --enable-lsp-logging
   

3. 检查插件状态：

   claude /plugin  # 查看“错误”选项卡
   

---

技能评估钩子

我们最强大的自动化功能之一是技能评估系统。它会在每次提交提示时运行，并智能地建议 Claude 应该激活哪些技能。

📄 文件： skill-eval.sh | skill-eval.js | skill-rules.json

工作原理

当你提交一个提示时，UserPromptSubmit 钩子会触发我们的技能评估引擎：

1. 提示分析 - 引擎会分析你的提示，寻找：

   • 关键词：简单的单词匹配（test、form、graphql、bug）
   • 模式：正则表达式匹配（\btest(?:s|ing)?\b、\.stories\.）
   • 文件路径：提取提及的文件（src/components/Button.tsx）
   • 意图：检测你试图完成的操作（create.*test、fix.*bug）

2. 目录映射 - 文件路径会被映射到相关的技能：

   {
     "src/components/core": "core-components",
     "src/graphql": "graphql-schema",
     ".github/workflows": "github-actions",
     "src/hooks": "react-ui-patterns"
   }
   

3. 置信度评分 - 每种触发类型都有对应的分数：

   {
     "keyword": 2,
     "keywordPattern": 3,
     "pathPattern": 4,
     "directoryMatch": 5,
     "intentPattern": 4
   }
   

4. 技能建议 - 置信度超过阈值的技能会被建议，并附上理由：

   需要激活的技能
   
   检测到的文件路径：src/components/UserForm.tsx
   
   匹配的技能（按相关性排序）：
   1. formik-patterns（高置信度）
      匹配：关键词“form”，路径“src/components/UserForm.tsx”
   2. react-ui-patterns（中等置信度）
      匹配：目录映射，关键词“component”
   

配置

技能定义在 skill-rules.json 中：

{
  "testing-patterns": {
    "description": "Jest 测试模式和 TDD 工作流程",
    "priority": 9,
    "triggers": {
      "keywords": ["test", "jest", "spec", "tdd", "mock"],
      "keywordPatterns": ["\\btest(?:s|ing)?\\b", "\\bspec\\b"],
      "pathPatterns": ["**/*.test.ts", "**/*.test.tsx"],
      "intentPatterns": [
        "(?:write|add|create|fix).*(?:test|spec)",
        "(?:test|spec).*(?:for|of|the)"
      ]
    },
    "excludePatterns": ["e2e", "maestro", "end-to-end"]
  }
}

添加到你的项目

1. 将钩子复制到你的项目中：

   cp -r .claude/hooks/ your-project/.claude/hooks/
   

2. 在 settings.json 中添加钩子：

   {
     "hooks": {
       "UserPromptSubmit": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
               "timeout": 5
             }
           ]
         }
       ]
     }
   }
   

3. 根据项目的技能和触发条件，自定义 skill-rules.json。

---

技能 - 领域知识

技能是以 Markdown 格式编写的文档，用于向 Claude 传授项目特定的模式和规范。

位置： .claude/skills/{skill-name}/SKILL.md

📄 示例：

• testing-patterns - TDD、工厂函数、模拟
• systematic-debugging - 四阶段调试方法
• react-ui-patterns - 加载状态、错误处理
• graphql-schema - 查询、突变、代码生成
• core-components - 设计系统、样式变量
• formik-patterns - 表单处理、验证

SKILL.md 的 Frontmatter 字段

字段	必需	最大长度	描述
name	是	64 个字符	只能包含小写字母、数字和连字符。应与目录名称一致。
description	是	1024 个字符	技能的作用及适用场景。Claude 会根据此描述决定何时应用该技能。
allowed-tools	否	-	Claude 可以使用的工具列表，用逗号分隔（例如：Read, Grep, Bash(npm:*)）。
model	否	-	特定的模型名称（例如：claude-sonnet-4-20250514）。

SKILL.md 的格式

---
name: skill-name
description: 此技能的作用及适用场景。请包含用户可能会提到的关键词。
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-20250514
---

# 技能标题

## 适用场景
- 触发条件 1
- 触发条件 2

## 核心模式

### 模式名称
```typescript
// 示例代码

反模式

不应该这样做

// 不良示例

整合

• 相关技能：other-skill

#### 编写技能的最佳实践

1. **保持 SKILL.md 内容聚焦** - 控制在 500 行以内；详细文档可放在单独引用的文件中。
2. **编写丰富的触发描述** - Claude 会通过语义匹配来判断何时应用这些技能。
3. **包含示例** - 展示良好和不良模式的代码。
4. **引用其他技能** - 展示技能之间的协作关系。
5. **使用精确的文件名** - 必须为 `SKILL.md`（区分大小写）。

---

### 代理 - 专用助手

代理是具有明确目标和专属提示的 AI 助手。

**位置：** `.claude/agents/{agent-name}.md`

**📄 示例：**
- [code-reviewer.md](.claude/agents/code-reviewer.md) - 带检查清单的全面代码审查
- [github-workflow.md](.claude/agents/github-workflow.md) - Git 提交、分支、PR

#### 代理的格式

```markdown
---
name: code-reviewer
description: 审查代码的质量、安全性及规范性。在编写或修改代码后使用。
model: opus
---

# 代理系统提示

你是一位资深代码审查员……

## 审查流程
1. 运行 `git diff` 查看更改
2. 应用审查清单
3. 提供反馈

## 审查清单
- [ ] 无 TypeScript `any`
- [ ] 存在错误处理
- [ ] 包含测试

代理配置字段

字段	必需	描述
name	是	小写加连字符
description	是	使用时机及原因（最多 1024 字符）
model	否	sonnet、opus 或 haiku
tools	否	用逗号分隔的工具列表

---

命令 - 斜杠命令

通过 /命令名 调用的自定义命令。

位置： .claude/commands/{命令名}.md

📄 示例：

• onboard.md - 深入任务探索
• pr-review.md - PR 审查流程
• pr-summary.md - 生成 PR 描述
• code-quality.md - 质量检查
• docs-sync.md - 文档同步

命令的格式

---
description: 命令列表中显示的简要说明
allowed-tools: Bash(git:*), Read, Grep
---

# 命令说明

你的任务是：$ARGUMENTS

## 步骤
1. 先做这个
2. 然后做这个

变量

• $ARGUMENTS - 所有参数作为一个字符串
• $1, $2, $3 - 单个位置参数

内联 Bash

当前分支：!`git branch --show-current`
最近的提交：!`git log --oneline -5`

---

GitHub Actions 工作流

使用 Claude Code 自动化代码审查、质量检查和维护。

📄 示例：

• pr-claude-code-review.yml - 自动 PR 审查
• scheduled-claude-code-docs-sync.yml - 每月文档同步
• scheduled-claude-code-quality.yml - 每周质量审查
• scheduled-claude-code-dependency-audit.yml - 每两周依赖更新

PR 代码审查

自动审查 PR 并响应 @claude 的提及。

name: PR - Claude Code 审查
on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

jobs:
  review:
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-opus-4-5-20251101
          prompt: |
            使用 .claude/agents/code-reviewer.md 标准审查此 PR。
            运行 `git diff origin/main...HEAD` 查看更改。

定期工作流

工作流	时间表	目的
代码质量	每周（星期日）	审查随机目录，自动修复问题
文档同步	每月（1号）	确保文档与代码变更一致
依赖审计	每两周（1号和15号）	在测试后安全地更新依赖

必需设置

将 ANTHROPIC_API_KEY 添加到你的仓库密钥中：

• 设置 → 密钥和变量 → 操作 → 新建仓库密钥

成本估算

工作流	频率	估计成本
PR 审查	每个 PR	~$0.05 - $0.50
文档同步	每月	~$0.50 - $2.00
反依赖审计	每两周	~$0.20 - $1.00
代码质量	每周	~$1.00 - $5.00

预计每月总计： ~$10 - $50（取决于 PR 数量）

---

最佳实践

1. 从 CLAUDE.md 开始

你的 CLAUDE.md 是基础。包括：

• 技术栈概述
• 关键命令
• 重要规则
• 目录结构

2. 逐步构建技能

不要试图一次性记录所有内容：

1. 从最常见的模式开始
2. 随着痛点出现逐步添加技能
3. 保持每项技能专注于一个领域

3. 使用钩子进行自动化

让钩子处理重复性任务：

• 保存时自动格式化
• 测试文件更改时运行测试
• 模式更改时重新生成类型
• 阻止对保护分支的编辑

4. 为复杂流程创建代理

代理非常适合：

• 代码审查（结合团队检查清单）
• PR 创建和管理
• 调试流程
• 任务入职

5. 利用 GitHub Actions

自动化维护：

• 每个 PR 上的 PR 审查
• 每周的质量扫描
• 每月的文档对齐
• 依赖更新

6. 对配置进行版本控制

提交所有内容，除了：

• settings.local.json（个人偏好）
• CLAUDE.local.md（个人笔记）
• 用户特定的凭据

---

本仓库中的示例

文件	描述
CLAUDE.md	示例项目记忆文件
.claude/settings.json	完整的钩子配置
.claude/settings.md	易于理解的钩子文档
.mcp.json	MCP 服务器配置（JIRA、GitHub、Slack 等）
代理
.claude/agents/code-reviewer.md	综合代码审查代理
.claude/agents/github-workflow.md	Git 工作流代理
命令
.claude/commands/onboard.md	深入探索任务
.claude/commands/ticket.md	JIRA/Linear 工单流程（阅读 → 实施 → 更新）
.claude/commands/pr-review.md	PR 审查流程
.claude/commands/pr-summary.md	生成 PR 摘要
.claude/commands/code-quality.md	质量检查
.claude/commands/docs-sync.md	文档同步
钩子
.claude/hooks/skill-eval.sh	技能评估封装脚本
.claude/hooks/skill-eval.js	Node.js 技能匹配引擎
.claude/hooks/skill-rules.json	模式匹配规则
技能
.claude/skills/testing-patterns/SKILL.md	TDD、工厂函数、模拟
.claude/skills/systematic-debugging/SKILL.md	四阶段调试
.claude/skills/react-ui-patterns/SKILL.md	加载/错误/空状态
.claude/skills/graphql-schema/SKILL.md	查询、突变、代码生成
.claude/skills/core-components/SKILL.md	设计系统、样式变量
.claude/skills/formik-patterns/SKILL.md	表单处理、验证
GitHub 工作流
.github/workflows/pr-claude-code-review.yml	自动 PR 审查
.github/workflows/scheduled-claude-code-docs-sync.yml	每月文档同步
.github/workflows/scheduled-claude-code-quality.yml	每周质量审查
.github/workflows/scheduled-claude-code-dependency-audit.yml	每两周依赖审计

---

了解更多

• Claude Code 文档
• Claude Code Action - GitHub Action
• Anthropic API

---

许可证

MIT - 将此作为你自己的项目的模板使用。

Claude Code Showcase 快速上手指南

本指南帮助中国开发者快速配置 claude-code-showcase，将 Claude Code 打造为符合团队规范、具备自动化能力的超级队友。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• 操作系统: macOS, Linux 或 Windows (WSL2 推荐)
• 运行时环境:
  • Node.js (v18+) - 用于运行 MCP 服务器和钩子脚本
  • npm 或 yarn
• 核心工具:
  • 已安装并配置好 Claude Code CLI 工具
  • Git (已初始化仓库)
• 可选集成:
  • 若需对接 JIRA/Linear，需准备相应的 API Token 和环境变量
  • 若需对接 GitHub Actions，需拥有仓库写入权限

安装步骤

1. 创建目录结构

在项目根目录下执行以下命令，生成标准的 .claude 配置目录：

mkdir -p .claude/{agents,commands,hooks,skills,rules}

2. 初始化项目记忆 (CLAUDE.md)

在项目根目录创建 CLAUDE.md 文件。这是 Claude 的“长期记忆”，启动时会自动加载。

# 项目名称

## 快速事实
- **技术栈**: React, TypeScript, Node.js
- **测试命令**: `npm run test`
- **Lint 命令**: `npm run lint`

## 关键目录
- `src/components/` - React 组件
- `src/api/` - API 层
- `tests/` - 测试文件

## 代码风格
- 启用 TypeScript strict mode
- 优先使用 interfaces 而非 types
- 禁止使用 `any`，请使用 `unknown`

3. 配置钩子与环境 (settings.json)

创建 .claude/settings.json 以定义自动化钩子（如：禁止在主分支直接编辑、自动格式化等）。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

4. 添加领域技能 (Skills)

创建第一个技能文件，让 Claude 学会团队的特定模式（例如测试规范）。 创建文件 .claude/skills/testing-patterns/SKILL.md：

---
name: testing-patterns
description: 本项目专用的 Jest 测试模式。当编写测试、创建 mock 或遵循 TDD 流程时使用。
---

# 测试模式规范

## 测试结构
- 使用 `describe` 块进行分组
- 使用 `it` 编写单个测试用例
- 遵循 AAA 模式：Arrange (准备), Act (执行), Assert (断言)

## Mock 规范
- 使用工厂函数：`getMockUser(overrides)`
- 仅 Mock 外部依赖，不要 Mock 内部模块

提示: description 字段至关重要，Claude 会根据其中的关键词自动判断何时激活该技能。

5. (可选) 配置外部集成 (MCP)

若需连接 JIRA 或 GitHub，在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-jira"],
      "env": {
        "JIRA_HOST": "${JIRA_HOST}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

注：请确保在终端环境中导出对应的环境变量。

基本使用

配置完成后，重启 Claude Code 会话即可生效。

场景 1：自动生成符合规范的代码

直接让 Claude 编写功能，它会自动读取 CLAUDE.md 和 skills 中的规范。

claude

(在交互中输入)

为用户个人资料页面创建一个上传头像的 React 组件，并编写相应的测试用例。

结果: Claude 将自动生成符合 TypeScript 严格模式、使用指定工厂函数进行 Mock 的代码和测试文件。

2. 场景 2：使用自定义命令处理工单

如果配置了 MCP 和 /ticket 命令，可以直接关联需求管理系统。

/ticket PROJ-123

结果:

1. Claude 自动从 JIRA 拉取 PROJ-123 的详情和验收标准。
2. 分析代码库现状。
3. 生成实现方案并开始编码。
4. 完成后更新工单状态并关联 PR。

3. 场景 3：触发自动化审查

提交代码后，Claude 可根据配置的 PostToolUse 钩子自动运行 Lint 修复，或通过 GitHub Action 触发深度代码审查 Agent。

请对刚才的修改进行代码审查，重点检查错误处理和加载状态。

结果: 调用 .claude/agents/code-reviewer.md 中定义的审查清单，输出详细报告。