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

一旦你配置好 Claude Code，就可以把它指向你的代码库，让它学习团队约定、吸收最佳实践，并持续打磨，直到它像一位超强队友一样工作。真正的突破在于构建一套稳固的可复用「技能」(skills)，再配上少量专用的「代理」(agents)，用于你最常执行的流程。

自定义 UI 库？ 我们准备了一份技能文档详细讲解如何使用它。写测试有技能，设计 GraphQL 也有技能，几乎所有事情都有说明。因此 Claude 生成的代码会天然符合我们的模式和标准。

自动化质量闸？ 我们通过钩子在提交前自动格式化代码、当测试文件变化时运行测试、TypeScript 类型检查，甚至阻止在 main 分支直接修改。Claude Code 还生成了多套 ESLint 自动化脚本，自定义规则和 lint 检查可以在代码评审前抓出问题。

深度代码审查？ 我们有一个代码审查代理，在修改完成后让 Claude 运行。它有一份详尽的检查清单，覆盖 TypeScript 严格模式、错误处理、加载状态、mutation 模式等等。当提交 PR 时，还有一个 GitHub Action 自动完成整套审查。

定期维护？ GitHub 工作流代理按计划运行：

• 每月文档同步：读取过去一个月的提交，确认文档仍然准确
• 每周代码质量扫描：随机抽取目录检查并自动修复
• 双周依赖审计：安���更新依赖并验证测试

智能技能建议？ 我们构建了一个技能评估系统，分析每一次提示，自动建议应该激活哪些技能，依据关键词、路径以及意图模式。

大量维护和质量工作都可以自动完成，运行得出奇顺畅。

JIRA/Linear 集成？ 我们通过 MCP 服务器把 Claude Code 连接到工单系统。Claude 可以阅读工单、理解需求、实现功能、更新状态，甚至在发现缺陷时创建新工单。/ticket 命令负责整个流程——读取验收标准、实施任务、将 PR 关联回工单。

我们甚至让 Claude Code 负责工单分诊。它会阅读工单、深入代码，并留下建议实现方案的备注。工程师接手时，基本已经完成了一半。

这里有太多唾手可得的机会，让人难以相信大家还没有广泛采用。

• 目录结构
• 快速开始
• 配置参考
  • CLAUDE.md - 项目记忆
  • settings.json - 钩子与环境
  • MCP Servers - 外部集成
  • LSP Servers - 实时代码智能
  • 技能评估钩子
  • Skills - 领域知识
  • Agents - 专用助理
  • Commands - 斜杠命令
• GitHub Actions 工作流
• 最佳实践
• 仓库中的示例

your-project/
├── CLAUDE.md                      # 项目记忆（备用路径）
├── .mcp.json                      # MCP 服务器配置（JIRA、GitHub 等）
├── .claude/
│   ├── settings.json              # 钩子、运行环境、权限
│   ├── settings.local.json        # 个人覆盖（已加入 .gitignore）
│   ├── 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

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

在项目根目录创建 CLAUDE.md，写入项目关键信息。完整示例见 CLAUDE.md。

# 项目名称

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

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

## 代码风格
- TypeScript 严格模式
- 优先使用 interface 而非 type
- 禁止 `any`——使用 `unknown`

创建 .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
          }
        ]
      }
    ]
  }
}

创建 .claude/skills/testing-patterns/SKILL.md。详见 testing-patterns/SKILL.md。

---
name: testing-patterns
description: 项目中的 Jest 测试范式。当编写测试、创建 mock 或进行 TDD 时使用。
---

# 测试模式

## 测试结构
- 使用 `describe` 进行分组
- 使用 `it` 描述单个测试
- 遵循 AAA：Arrange、Act、Assert

## Mock
- 使用工厂函数：`getMockUser(overrides)`
- mock 外部依赖，而不是内部模块

提示： description 字段非常关键——Claude 依靠它决定何时激活技能，请写入用户可能提到的关键词。

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

优先级（由高到低）：

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

建议内容：

• 项目技术栈与架构概览
• 关键命令（测试、构建、部署等）
• 代码风格指南
• 重要目录与用途
• 必须遵守的规则与约束

📄 示例： CLAUDE.md

settings.json 是钩子、环境变量与权限的总配置。

位置： .claude/settings.json

📄 示例： settings.json ｜ 人类可读说明

{
  "block": true,          // 是否阻止行为（仅 PreToolUse）
  "message": "Reason",   // 展示给用户的原因
  "feedback": "Info",    // 非阻塞反馈
  "suppressOutput": true, // 隐藏命令输出
  "continue": false       // 是否继续执行
}

• 0 - 成功
• 2 - 阻塞错误（仅 PreToolUse，直接阻止）
• 其他 - 非阻塞错误

MCP（Model Context Protocol）服务器让 Claude Code 连接到 JIRA、GitHub、Slack、数据库等外部工具，实现“读取工单 → 实现功能 → 更新状态”等流程。

位置： .mcp.json（项目根目录，纳入版本控制）

📄 示例： .mcp.json

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

配置好 JIRA 的 MCP 服务器后，Claude 会获得 jira_get_issue、jira_update_issue、jira_create_issue 等工具。

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

字段说明：

{
  "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}"
      }
    }
  }
}

可实现的能力：

• 读取工单详情、验收标准和评论
• 更新工单状态（To Do/待办 → In Progress/进行中 → In Review/审核中）
• 追加进度评论
• 创建新工单处理发现的缺陷
• 在 PR 中自动关联工单

结合 /ticket 命令 的工作流示例：

你：/ticket PROJ-123

Claude：
1. 正在获取 PROJ-123...
   “Add user profile avatar upload（添加用户头像上传）”

2. 阅读验收标准...
   - Upload button on profile page（在个人资料页提供上传按钮）
   - Support JPG/PNG up to 5MB（支持不超过 5MB 的 JPG/PNG）
   - Show loading state（展示加载状态）

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

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

5. [实现功能...]

6. 将 JIRA 状态更新为 “In Review（审核中）”
   评论：“PR #456 ready for review（PR #456 已准备好评审）”

7. 创建并关联 PR...

工单系统：

{
  "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} - 若未设置则使用默认值

在 shell 配置或 .env 中设置（切勿提交敏感信息）：

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

在 settings.json 中开启自动批准：

{
  "enableAllProjectMcpServers": true
}

或只允许特定服务器：

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

LSP（Language Server Protocol）让 Claude 获得实时的类型信息、错误提示、补全与导航能力。编辑 TypeScript 时，Claude 能立即看到类型错误；��用函数时可以跳转定义，大幅提升代码生成质量。

在 settings.json 的 enabledPlugins 中加入插件：

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

在 .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  # 检查 Errors 标签

我们最强大的自动化之一是技能评估系统。它在每次提交提示时运行，智能建议需要激活的技能。

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

1. 提示分析 —— 引擎会检查：
   • 关键词：简单词匹配（test、form、graphql 等）
   • 正则模式：如 \btest(?:s|ing)?\b
   • 文件路径：提取 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. 技能建议 —— 超过阈值的技能会附理由列出。

技能在 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。

技能是教给 Claude 项目特定模式的 Markdown 文档。

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

📄 示例：

• testing-patterns：TDD、工厂函数、mock
• systematic-debugging：四步调试法
• react-ui-patterns：加载/错误/空状态
• graphql-schema：���询、mutation、codegen
• core-components：设计系统与 tokens
• formik-patterns：表单和校验

---
name: skill-name
description: 功能与使用时机。
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-20250514
---

# 技能标题

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

## 核心模式

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

// 错误示例

• 相关技能：other-skill

#### 最佳实践

1. **保持聚焦** —— 控制在 500 行以内，详细内容另拆文件
2. **描述要富含触发词** —— Claude 依赖 description 做语义匹配
3. **包含示例** —— 提供好坏示例
4. **互相引用** —— 展示技能如何协作
5. **确保文件名为 `SKILL.md`** —— 区分大小写

---

<a id="agents---specialized-assistants"></a>
### Agents - 专用助理

代理是拥有独立提示词的 AI 助手。

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

**📄 示例：**
- [code-reviewer.md](.claude/agents/code-reviewer.md)：全面代码审查清单
- [github-workflow.md](.claude/agents/github-workflow.md)：Git 工作流代理

#### 代理格式

```markdown
---
name: code-reviewer
description: 检查代码质量、安全性与规范。写完代码后使用。
model: opus
---

# Agent System Prompt

You are a senior code reviewer...

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

## 检查清单
- [ ] 禁止 TypeScript `any`
- [ ] 必须有错误处理
- [ ] 包含测试

自定义命令以 /command-name 形式调用。

位置： .claude/commands/{command-name}.md

📄 示例：

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

---
description: 命令列表中的简短描述
allowed-tools: Bash(git:*), Read, Grep
---

# 命令说明

你的任务：$ARGUMENTS

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

• $ARGUMENTS —— 传入的所有参数
• $1, $2, $3 —— 单个位置参数

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

通过 GitHub Actions 自动化代码审查、质量检查与维护。

📄 示例：

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

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

name: PR - Claude Code Review
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: |
            Review this PR using .claude/agents/code-reviewer.md standards.
            Run `git diff origin/main...HEAD` to see changes.

在仓库 Secrets 中添加 ANTHROPIC_API_KEY：Settings → Secrets and variables → Actions → New repository secret。

估算月总成本： ~$10 - $50（取决于 PR 数量）

包含：

• 技术栈概览
• 关键命令
• 强制规则
• 目录结构

不要一次写完所有内容：

1. 先记录最常用的模式
2. 随痛点增加再补充
3. 让每个技能聚焦一个领域

交给钩子处理重复任务：

• 保存时自动格式化
• 测试文件变动时运行测试
• schema 变化时重生成 types
• 阻止在受保护分支上编辑

适用场景：

• 代码审查（结合自定义清单）
• PR 创建与管理
• 调试流程
• 任务调研/上手

自动化维护：

• PR 审查
• 每周质量巡检
• 每月文档对齐
• ���赖更新

提交所有文件，除了：

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

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

MIT - 欢迎将其作为项目模板使用。