Claude Code 操作指南及最佳实践

前言：为规范Claude Code的使用流程，提升研发效率、保障代码质量与系统安全，结合Claude Code六层架构（CLAUDE.md、Tools/MCP、Skills、Hooks、Subagents、Verifiers）核心逻辑，结合公司业务场景与研发规范，制定本操作指南。本指南适用于公司所有使用Claude Code进行研发、测试、运维等相关工作的人员，旨在解决使用过程中上下文混乱、工具滥用、验证缺失等常见问题，实现Claude Code的工程化、标准化使用。

一、核心认知：Claude Code不是ChatBot，是分布式开发系统

所有使用者需明确：Claude Code的核心价值的是作为智能编码代理，参与项目全生命周期，而非简单的代码生成或聊天工具。其运行依赖“收集上下文→采取行动→验证结果→迭代优化”的核心循环，使用时需以“工程化系统设计”思维替代“ Prompt调优”思维，重点关注上下文管控、约束落地、隔离执行与验证闭环，避免因使用方式不当导致效率低下、代码隐患等问题。

关键数据参考：根据行业实践验证，采用标准操作规范的Claude Code使用场景，代码输出准确率可提升78%，上下文消耗降低62%，返工率减少85%，团队协作效率提升50%以上，是提升研发效能的核心工具之一。

二、基础操作规范（必遵循）

2.1 环境配置要求

• 统一版本：所有团队需使用Claude Code v2.1.3及以上版本（支持完整的Skills、Hooks、Subagents功能），禁止使用旧版本导致功能缺失或兼容问题，可通过claude --version命令检查版本。

• 权限管控：严格按照“最小权限原则”配置使用权限，普通研发人员仅开放“编辑文件、基础工具调用”权限；管理员开放“Subagents创建、Hooks配置、权限审计”权限；禁止使用--dangerously-skip-permissions参数，避免跳过权限校验导致系统风险或数据泄露。

• 环境隔离：生产环境与开发/测试环境分开使用，生产环境禁止直接使用Claude Code执行修改操作，需先在测试环境验证通过后，再手动同步至生产环境；敏感项目需使用沙箱化bash工具，通过/sandbox命令定义操作边界，强化隔离防护。

2.2 会话管理规范

• 会话命名：每个会话需以“项目名称-任务类型-时间”命名（例：user-management-system-code-review-20260401），便于后续追溯与协作。

• 会话清理：任务完成后及时清理会话（使用/clear命令），避免上下文冗余；长会话每2小时检查一次上下文消耗（使用/context命令），必要时使用/compact命令压缩，压缩规则需提前在CLAUDE.md中明确。

• 模式切换：根据任务类型选择对应权限模式，默认模式用于不熟悉的项目或高风险操作，编辑模式用于日常开发提升效率，计划模式用于复杂任务（如重构、跨模块开发），通过Shift + Tab键循环切换，切换后需确认状态栏显示正确。

• 任务交接：长任务或跨人员交接时，需生成HANDOFF.md文件，明确当前进度、已尝试方案、未解决问题及下一步计划，新会话仅加载该文件即可接续工作，避免依赖系统压缩摘要导致信息丢失。

三、各模块最佳实践（核心重点）

3.1 CLAUDE.md：项目契约，极简且可执行

CLAUDE.md是Claude Code的“项目宪法”，是所有操作的核心约束，需严格遵循“短、硬、可执行”原则，控制在200行以内，杜绝冗余内容，仅包含AI无法自行推断的核心信息，统一放置在项目根目录，提交至Git共享，确保团队所有成员的Claude遵循同一套规范。

必包含内容（公司标准模板）

• 项目基础信息：项目名称、技术栈、核心目标、禁止操作（如禁止无where条件的delete/update、硬编码密钥、修改生产配置等）。

• 常用命令：构建、测试、格式化、部署的标准化bash命令（例：npm run build、cargo test等），避免重复输入。

• 代码规范：公司统一的编码风格（如命名规则、注释标准、函数复杂度限制）、分支命名规范（feature/xxx、bugfix/xxx）、PR流程。

• 压缩规则（Compact Instructions）：明确压缩时需优先保留的内容，示例如下： `## Compact Instructions When compressing, preserve in priority order:

1. Architecture decisions (NEVER summarize)
2. Modified files and their key changes
3. Current verification status (pass/fail)
4. Open TODOs and rollback notes
5. Tool outputs (can delete, keep pass/fail only)`

• 目录索引：核心目录、高风险模块位置（如src/auth、src/db），引导AI按需读取文档，避免上下文冗余。

禁止行为

• 禁止将大型参考文档、完整工作手册塞进CLAUDE.md，此类内容需拆至Skills的supporting files中。

• 禁止不更新CLAUDE.md，当项目规范、架构发生变更时，需第一时间同步更新，避免AI使用过时规则。

• 禁止在CLAUDE.md中写入无关内容（如个人备注、临时测试指令），保持文件简洁性。

3.2 Tools/MCP：按需配置，降低上下文开销

Tools是Claude Code的“动作能力”，MCP（模型上下文协议）负责对接外部系统（如GitHub、Jira），配置核心是“精简、精准”，减少上下文固定开销，避免因工具过多导致AI选择混乱或token浪费。

最佳实践

• 工具命名：按系统或资源分层命名（例：github_pr_、jira_issue_），便于AI快速识别与调用。

• 工具筛选：仅配置项目必需的工具，本地Shell可完成的操作（如简单文件编辑、基础命令执行），不额外配置工具；避免暴露过多底层碎片工具，优先合并为高层任务工具。

• 工具优化：对大响应工具，配置response_format: concise / detailed，根据任务需求选择响应模式；错误响应需包含“修正指引”，避免仅返回错误码导致AI无法处理。

• MCP管控：对接MCP Server（如GitHub、Jira）时，仅加载必需的工具定义，避免多Server叠加导致固定开销过高（单个MCP Server工具定义约4000-6000 tokens，最多对接3个核心Server）；新增MCP Server需经管理员审核，确保安全性。

• 工具迭代：定期清理无用工具（每月一次），对使用频率低于1次/月的工具，直接移除，避免占用上下文空间。

典型场景示例

提问类需求（如任务中途需确认用户需求），直接使用独立的AskUserQuestion工具，避免在已有工具中添加提问参数，确保AI能明确暂停并提问，提升交互稳定性。

3.3 Skills：标准化工作流，按需加载复用

Skills是Claude Code的“标准化操作手册”，核心价值是复用高频流程、规范操作步骤，避免重复解释，只要重复3次以上的流程，均需封装为Skill，统一放置在.claude/skills/目录，提交至Git共享，实现团队复用。

Skill设计规范

• 结构清晰：每个Skill包含“描述符+核心步骤+输入输出+停止条件”，正文仅放导航和核心约束，大资料拆至supporting files（如runbook.md、examples.md），目录结构示例： .claude/skills/ └── incident-triage/ ├── SKILL.md ├── runbook.md ├── examples.md └── scripts/ └── collect-context.sh

• 描述精准：描述符需明确“何时使用”，而非“是什么”，控制在10 tokens以内（例：高效描述：Use for PR reviews with focus on correctness；低效描述：This skill helps you review code changes in Rust projects…）。

• 风险管控：有副作用的Skill（如修改配置、执行部署命令），需显式设置disable-model-invocation: true，禁止AI自动调用，仅允许手动触发。

• 分类管理：按场景分为三类Skill，统一规范格式：

  • 检查清单型（质量门禁）：如发布前检查，明确所有必过项（例：cargo build –release passes、版本号更新、CHANGELOG同步）；

  • 工作流型（标准化操作）：如配置迁移，包含备份、 dry run、应用、验证、回滚全步骤；

  • 领域专家型（决策框架）：如运行时诊断，明确证据收集步骤、决策矩阵、输出格式。

禁止行为

• 禁止一个Skill覆盖多个场景（如同时包含代码评审、部署、调试），避免逻辑混乱。

• 禁止Skill正文过长，避免常驻上下文的描述符占用过多token。

• 禁止低频Skill（使用频率<1次/月）继续保留，需移除并转为文档记录。

3.4 Hooks：强制约束，提前规避风险

Hooks是“确定性执行逻辑”，用于在Claude Code执行操作前后，强制插入校验、格式化、通知等逻辑，核心价值是“提前发现错误、降低返工成本”，统一配置在.claude/hooks.json，由管理员统一维护，团队成员可提交修改申请。

适用场景（公司必配置）

• 编辑后校验：PostToolUse钩子，对代码编辑操作（如修改.rs、.js文件），自动执行lint、格式检查、基础语法校验（例：cargo check、eslint），限制输出长度（如| head -30），避免输出冗余污染上下文。

• 安全防护：PreEdit钩子，阻断对受保护文件（如生产配置、核心架构文件）的修改，避免误操作。

• 上下文注入：SessionStart钩子，自动注入当前Git分支、环境变量等动态上下文，确保AI了解当前工作环境。

• 任务通知：Notification钩子，任务完成后自动推送通知（如企业微信、邮件），同步任务状态（成功/失败、验证结果）。

配置示例

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "pattern": "*.rs",
        "hooks": [
          {
            "type": "command",
            "command": "cargo check 2>&1 | head -30",
            "statusMessage": "Running cargo check..."
          }
        ]
      }
    ],
    "Notification": [
      {
        "type": "command",
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
      }
    ]
  }
}

禁止行为

• 禁止在Hooks中配置复杂语义判断、长时间运行的业务流程，此类逻辑需放在Skill或Subagents中。

• 禁止随意修改Hooks配置，修改需经管理员审核，确保不影响团队整体使用。

3.5 Subagents：隔离执行，保护主线上下文

Subagents是从主会话派出去的独立Claude实例，核心价值是“隔离任务、承担脏活累活”，避免大量中间输出污染主线上下文，适用于扫代码库、跑测试、多维度审查等场景；公司同时支持Agent Teams功能（实验性），用于复杂任务的多AI协作，需按规范启用与使用。

Subagents最佳实践

• 任务隔离：每个Subagents仅负责单一、可重启的任务（例：代码扫描、单元测试执行、文档生成），不允许一个Subagents处理多个无关任务。

• 权限约束：配置时明确限定工具（tools/disallowedTools）、模型（探索用Haiku省成本，关键执行用Opus）、上下文大小（按需分配，不默认全给200K），禁止给Subagents与主线程相同的权限，尤其禁止修改主线程核心文件。

• 结果反馈：Subagents完成任务后，以结构化格式（JSON/Markdown表格）返回结果，仅传递摘要信息，不返回完整中间输出；失败时需包含失败原因、重试建议。

• 资源管控：定期清理闲置Subagents（任务完成后立即清理），避免资源泄漏；超时设置为30分钟，失败超过3次自动回传主线程，由人工处理。

Agent Teams使用规范（实验性）

• 启用条件：仅用于复杂任务（如多模块并行开发、多维度PR审查、跨层协调），简单任务禁止使用，避免资源浪费。

• 团队配置：由Team Lead（主会话）创建团队、分配任务，Teammates（独立Claude实例）各自负责专属模块，支持In-Process模式（默认）和Split Panes模式（需tmux或iTerm2支持）。

• 协作规范：Teammates可直接互相通信，共享任务列表，支持任务认领；复杂任务需要求Teammates先提交计划，经Lead批准后再执行，避免无效操作。

• 注意事项：启用前需通过环境变量或settings.json开启（export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1），生产环境禁止使用，避免实验性功能带来的风险。

禁止行为

• 禁止主会话闲置，将所有任务丢给Subagents/Agent Teams，主会话需负责决策、协调、验收。

• 禁止Subagents/Agent Teams权限过大，避免修改核心代码、执行危险命令。

3.6 Verifiers：验证闭环，保障代码质量

验证是Claude Code工程化的“最后一公里”，核心是“每步可测、结果明确、可回滚”，杜绝“看起来对但跑不起来”的代码，建立三层验证体系，覆盖从编辑到发布的全流程。

三层验证体系（必执行）

• 即时验证（Hook层）：Edit操作后，通过Hooks自动执行lint、格式检查、基础语法校验，即时阻断低级错误。

• 任务验证（Skill层）：功能完成后，调用对应Skill执行单元测试、集成测试、场景测试，确保功能符合需求；测试覆盖率需≥80%，未达标的需补充测试用例。

• 发布验证（CLI层）：合并代码前，执行全量测试、性能测试、安全扫描，由管理员审核验证结果，确认无风险后，方可合并至主分支；需明确回滚方案，确保出现问题可快速回滚。

验证结果规范

验证完成后，需以结构化格式记录状态，示例如下：

## Verification Status
- Unit Tests: ✅ 12/12 passed
- Integration: ✅ 3/3 passed
- Lint: ✅ clean
- Coverage: 🟡 82% (target 80%)
- Risk: 🟡 Minor unsafe block in parser
- Rollback Plan: Available (v1.2.3 tag)

禁止行为

• 禁止跳过任何一层验证，尤其是发布验证，避免带隐患代码上线。

• 禁止验证结果模糊（如仅标注“测试通过”，不标注具体通过率、风险点）。

• 禁止无回滚方案的发布，所有发布操作必须提前明确回滚步骤。

四、项目结构标准化（公司统一模板）

所有使用Claude Code的项目，需遵循以下目录结构，确保配置统一、易于协作，目录需提交至Git，实现团队共享：

.claude/
├── CLAUDE.md          # 核心契约、压缩规则、禁止事项（根目录必放）
├── rules/             # 路径/语言规则（按语言/目录拆分，如rust.md、frontend.md）
├── skills/            # 按需工作流（按场景分类，如release-check、config-migration）
├── hooks.json         # 强制校验规则（管理员维护）
├── agents.json        # Subagent/Agent Teams定义（按需配置）
└── VERSION            # 版本标记（同步项目版本，便于追溯）
# 其他项目原有目录（如src、docs、tests等）保持不变

五、安全规范（红线不可碰）

• 敏感信息保护：禁止向Claude Code输入公司机密（如数据库密码、API密钥、核心业务逻辑）；API密钥需加密存储，禁止硬编码在代码或配置文件中，遵循公司凭证管理规范。

• 命令安全：禁止Claude Code执行危险命令（如rm -rf /*、curl/wget等网络请求命令），此类命令需手动执行并二次确认；可疑bash命令需手动审核，即使已列入白名单。

• 输入安全：避免将不受信任的内容直接传递给Claude Code，防止提示注入攻击；发现可疑行为，使用/bug命令报告，不公开披露安全漏洞。

• 审计管控：管理员需定期审计Claude Code使用日志（每月一次），检查权限滥用、危险操作等情况；使用/permissions命令定期审计权限设置，及时调整不合理权限。

• Windows环境注意：禁止在Windows环境启用WebDAV，避免绕过权限系统导致网络请求风险，因WebDAV已被Microsoft弃用，存在安全隐患。

六、常见问题与解决方案

七、附则

• 本指南自发布之日起生效，所有使用Claude Code的人员需严格遵循；若违反规范导致系统故障、代码隐患或信息泄露，将追究相关人员责任。

• 本指南将根据Claude Code版本更新、公司业务发展，由技术部定期修订（每季度一次），修订后将及时同步至所有相关人员。

• 若在使用过程中遇到疑问、建议或发现问题，可联系技术部管理员反馈，统一协调解决。

• Claude Code
• 操作指南
• 最佳实践