Claude 代码设置终极指南：钩子、技能与动作
Claude 代码配置终极指南：Hooks、技能与操作
Claude Code 将普通代码库转变为能够阅读、编写、重构甚至管理工单的团队成员。无论你是单打独斗的开发者还是大型团队的一员，本教程将为你提供完整、实操的配置，覆盖： - 通过
CLAUDE.md的项目记忆 - 运行时 Hooks、环境变量以及命令限制 - 可复用的“技能”用于模式、测试与架构 - MCP 服务器用于 JIRA、GitHub、Slack 等 - 实时诊断的 LSP 集成 - 自定义代理与斜杠命令 - GitHub Actions 用于 PR 评论、质量检查与计划任务
1. 为什么使用 Claude Code？
传统的 LLM 助手往往把代码视为纯文本。Claude Code 改变了这一点：
| 功能 | 益处 |
|---|---|
| 项目记忆 | Claude 记住堆栈、风格指南与常见模式。 |
| Hooks | 自动格式化、测试与分支保护。 |
| 技能 | 教授 Claude 如何编写测试、GraphQL 或设计系统组件。 |
| 代理 | 为 PR 审核、调试或工作流编排提供专属助手。 |
| MCP 服务器 | 通过单一 JSON 配置连接外部工具（JIRA、GitHub、Slack）。 |
| LSP | 在代码生成过程中实时提供类型信息与诊断。 |
凭借这些功能，Claude 成为可信赖的同事，而非简单的代码生成工具。
2. 项目布局概览
your‑project/
├── .claude/
│ ├── agents/ # 自定义 AI 代理
│ ├── commands/ # 斜杠命令
│ ├── hooks/ # Hook 脚本与规则
│ ├── skills/ # 领域特定知识
│ ├── settings.json # 全局 Hook 与环境变量
│ └── settings.md # 供人阅读的文档
├── .mcp.json # MCP 服务器配置 (JIRA, GitHub, 等)
├── .github/workflows/ # GitHub Actions
├── CLAUDE.md # 项目记忆 – 顶层
└── README.md
小贴士：将任何用户特定的覆盖配置存放在
.claude/settings.local.json或个人的CLAUDE.local.md中——这些文件应当被 Git 忽略。
3. 快速开始：创建样板
mkdir -p .claude/{agents,commands,hooks,skills}
# 基础 CLAUDE.md – 根据你的堆栈进行编辑
cat <<'EOF' > CLAUDE.md
# My Awesome Project
## Stack
- React
- TypeScript
- Node.js
## Key Directories
- src/components/ # UI
- src/api/ # API 层
- tests/ # Jest 测试
## Code Style
- TypeScript 严格模式
- 优先使用接口而非类型
- 无 `any` – 使用 `unknown`
EOF
# 简单的 settings.json，包含一个 PreToolUse Hook
cat <<'EOF' > .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
}
]
}
]
}
}
EOF
运行
git add -A && git commit -m "Initial Claude Code configuration"以保存脚手架。
4. 项目记忆：CLAUDE.md
CLAUDE.md 是 Claude 的持久记忆文件，在每次会话启动时加载。保持简洁但完整：
- 堆栈与架构 – 快速堆栈概览。
- 关键命令 –
npm run test、npm run lint、npm run build。 - 代码风格指南 – 任何 lint 规则、类型严格性。
- 关键目录 – 组件、工具库或测试所在位置。
- 特殊约束 – 例如：不允许在
main分支上编辑。
Claude 首先读取此文件，因此请将最重要的信息放在顶部。
5. Hooks 与环境变量：.claude/settings.json
Hooks 允许你拦截工具调用或用户提示。典型配置会包含：
| Hook 事件 | 常见用途 |
|---|---|
PreToolUse |
阻止在受保护分支编辑或在提交前要求运行测试。 |
PostToolUse |
在代码更改后自动格式化或运行测试。 |
UserPromptSubmit |
触发技能评估引擎。 |
Stop |
决定 Claude 是否继续多步骤流程。 |
示例：阻止在 main 上编辑
"PreToolUse": [
{"matcher": "Edit|Write", "hooks": ["if [ \"$(git branch --show-current)\" != \"main\" ]; then echo 'Allowed'; else echo 'Blocked'; fi"]}
]
你也可以为秘钥（例如 JIRA API 令牌等）添加环境变量。该文件会被提交，因为秘钥以 ${VAR} 格式引用，运行时才加载。
6. 技能：可复用的领域知识
技能是 Markdown 文件，用来教 Claude 在你的风格下编写代码。每个技能都位于 .claude/skills/{skill-name}/SKILL.md。
技能 Frontmatter 示例
---
name: testing-patterns
description: Jest 测试模式，适用于此项目。编写测试、创建 mock 或遵循 TDD 工作流时使用。
---
description 字段非常重要 – Claude 用它来判断何时激活该技能。请包含自然语言关键词（如 test、jest、mock）。
示例技能内容
# Testing Patterns
## Arrange-Act-Assert
```ts
// Arrange
const mockUser = getMockUser();
// Act
const result = login(mockUser);
// Assert
expect(result).toBeTruthy();
Mocking
优先使用工厂函数而非全局 mock，以保持测试可复现。
添加新技能
- 创建
.claude/skills/{skill-name}/SKILL.md。 - 写一个简洁的描述。
- 编写代码示例。
- 如有需要，更新
skill-rules.json以映射触发条件。 - 将技能目录加入 Git 并提交。
7. 技能评估 Hook
当用户提交提示时，UserPromptSubmit Hook 会运行一个小型引擎，寻找：
- 关键词 – 例如
write test。 - 路径模式 – 例如
src/components/*。 - 意图模式 – 通过正则捕获常见请求。
- 目录映射 – 将文件路径映射到技能名称。
该 Hook 输出 JSON，指定要激活的技能，例如：
{"activate": ["testing-patterns", "react-ui-patterns"]}
小贴士：保持
skill-rules.json简洁 – 仅在新模式出现时添加规则。
8. MCP 服务器：连接外部工具
MCP（Model Context Protocol）服务器让 Claude 直接访问 JIRA、GitHub、Slack、Sentry 或 Postgres 等服务。请在 .mcp.json 中配置。
示例：JIRA 与 GitHub
{
"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}"}
},
"github": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic/mcp-github"],
"env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
}
}
}
将真实令牌存放在环境变量或
.env文件中，切勿提交。
/ticket 命令
斜杠命令 /ticket 能读取 JIRA 问题，生成分支，实施请求功能，并自动关闭工单。详细说明请参阅 .claude/commands/ticket.md。
9. LSP 支持
添加 Language Server Protocol 插件，让 Claude 获得实时诊断：
// .claude/settings.json
"enabledPlugins": {
"typescript-lsp@claude-plugins-official": true,
"pyright-lsp@claude-plugins-official": true
}
确保已安装 LSP 二进制（例如 npm i -g typescript-language-server）。LSP 能让 Claude：
- 诊断 – 编辑时触发类型错误。
- Intellisense – 提供函数签名与类型信息。
- 导航 – 跳转到定义。
- 补全 – 上下文感知的建议。
10. 代理与命令
代理
代理是专注型助手。例如 code-reviewer 代理会自动执行检查清单并在 PR 上发表评论。
---
name: code-reviewer
description: 对 TypeScript 代码进行风格、安全与测试审核。
model: opus
---
命令
斜杠命令执行自定义工作流。例如 /pr-review 解析 PR，审阅变更并留下评论。
---
description: 使用标准检查清单审阅当前 PR。
allowed-tools: Bash(git:*), Read, Grep
---
将 markdown 文件放在 .claude/commands/ 中，并在 GitHub Actions 中引用。
11. GitHub Actions 自动化
通过在 .github/workflows/ 中编写工作流，实现质量门控、文档同步与依赖审计的自动化。典型示例：
- 自动 PR 审核 – 在 PR 事件触发时运行 Claude
code-reviewer。 - 定时文档同步 – 每月运行一次，确保文档与最新代码保持一致。
- 每周代码质量 – 随机扫描目录并进行自动修复。
- 双周依赖审计 – 安全更新并验证测试。
最小 PR 审核工作流示例：
name: PR - Claude Review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
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.
将
ANTHROPIC_API_KEY添加到 Repository Secrets 以获得 API 访问权限。
12. 最佳实践
- 从 CLAUDE.md 开始 – 保持简洁但完整。
- 逐步构建技能 – 关注高影响模式。
- 使用 Hooks 批量处理 – 避免手动 lint 或测试失败。
- 为复杂工作流创建代理 – 如 bug 分流、PR 摘要等。
- 用 GitHub Actions 自动化 – 定时执行质量扫描与文档同步。
- 对配置进行版本管理 – 所有文件除个人覆盖外均提交。
- 安全存储敏感数据 – 使用环境变量，绝不提交秘钥。
- 监控成本 – 运行成本估算表以保持使用可预见。
13. 结束语
凭借此配置，你的代码仓库现在具备：
- 自知之明 – Claude 能理解堆栈、风格与约定。
- 自动化 – 代码格式化、测试与质量门控全自动运行。
- 连接 – Ticket、PR 与聊天直接集成到 Claude 的工作流。
- 可扩展 – 十分钟内即可添加新技能、代理与命令。
先克隆仓库，按你自己的堆栈自定义示例，然后让 Claude 成为你从未发现的团队伙伴。
祝编码愉快！