I. 不止是问答：重新认识 Claude Code
1. 从对话工具到“工程协作者”
Claude Code 是一个AI-powered coding assistant，不像普通聊天机器人只负责回答问题，而是能够直接嵌入开发者的本地系统底层。它被赋予了直接读取整个代码库、编辑多层级文件、执行系统终端命令以及与本地开发工具链深度交互的更高级权限。
这种设计使得人工智能不再仅仅是一个局部逻辑的生成器，而是一个能够进行自主需求理解、任务计划制定、外部工具调用和多智能体并行协作（Subagents）的虚拟工程师。
换句话说，当描述一个功能需求时，Claude 会主动探索代码库、制定实施计划并实现它，而不是等你编写代码后再来查看。这种自主性让 Claude 更像是一位“工程协作者”，能够接管从编写文档、运行构建到修复 Bug 等各种任务。
2. Claude Code 与传统 IDE / Copilot 的差异
传统的代码补全工具和各类 IDE 插件主要依赖于光标位置的局部上下文，其核心运算逻辑是“基于前文的概率预测”与“行级或函数级的自动补全”。这种机制在处理单文件内的标准算法闭环时表现优异，但在面对跨文件重构、系统级架构设计、处理复杂的环境依赖或需要深层业务逻辑理解的任务时，往往会因为缺乏全局视野而显得力不从心。
Claude Code 采取了截然不同的技术路线，它放弃了对特定图形界面（GUI）的依附，回到了开发者最为熟悉、扩展性最强且权限最高的交互界面——终端（Terminal）。终端的纯文本输入输出特性（Text-in, Text-out）消除了图形界面的视觉干扰与操作壁垒，为智能体提供了最底层的控制权与最纯粹的计算环境。
这种终端原生的架构带来了几个根本性的差异：
- 首先是全局视野与自主探索能力。传统工具被动等待开发者的光标触发，而 Claude Code 能够主动调用底层的 grep、glob 和文件系统遍历命令，对未知的庞大代码库进行自主探索与语义地图构建。
- 其次是环境执行反馈机制的建立。Claude Code 可以直接在终端中运行项目的测试脚本（如 pytest、npm run test 或 cargo test），并根据编译器或测试框架抛出的错误堆栈日志进行深度推理与自我修正（Self-correction），真正实现了从“编写代码”到“验证代码”的全自动闭环。
- 最后，它的安全哲学也与传统工具不同。考虑到终端命令的破坏性，Claude Code 在涉及敏感或破坏性操作（如删除文件、修改数据库结构）时，默认要求人类进行显式批准，这种在能力与监督之间取得的平衡，使其既强大又可控。
3. 为什么“默认用法”远远不够
尽管 Claude Code 具备强大的开箱即用能力，但如果仅仅以“默认用法”（即类似于使用 ChatGPT 的一次性指令输入）来驱动它，将导致极大的生产力损耗和频繁的工程灾难。
在未施加适当系统级约束的情况下，智能体易产生幻觉、偏离项目既定的架构规范等。在早期使用 Claude Code 时，习惯于一次性抛出极其庞大且模糊的需求（例如“构建我的整个电商后端和前端管理系统”）。由于大型语言模型的注意力机制限制，这种指令往往导致模型在庞大的上下文窗口中迷失重点，最终输出逻辑断层、无法编译或漏洞百出的代码。
接下来的章节将介绍如何在项目级别提供持久上下文（CLAUDE.md）、可复用模块（Skills）、以及工具连接（MCP）等，使 Claude Code 超越简单问答模式发挥最大效能。
II. 工程上下文：仓库级约束
A. 为什么需要仓库级约束
大型语言模型的底层运算逻辑是无状态（Stateless）的函数映射。这意味着在每次新的命令行会话启动时，或者发生了上下文 Compact 时，Claude Code 对当前代码库的目录架构、技术栈偏好、团队历史架构决策以及变量命名约定处于基本“失忆”的状态。
为了使 Claude Code 能够保持高效产出，必须在每次会话初始化时，系统性地向其注入关于当前项目的“世界观”和“工程法则”。
通过在项目的根目录（或特定子目录）放置标准化的 Markdown 配置文件，系统能够在不增加人类输入负担的前提下，自动且强制地向大模型的系统提示词（System Prompt）中注入核心规范。这些约束文档不仅明确了智能体“应该按照什么标准做事”，更重要的是，它们划定了智能体“绝对不可触碰的红线”，从而大幅削减了因误解导致的返工成本和代码腐化风险。
B. AGENT.md / CLAUDE.md
AGENT.md 是一个多厂商共同认可标准规范文件（CLAUDE.md 就是 Anthropic 为 Claude Code 量身定制的专属执行法则）。它们的主要目标是一致的：为各种不同的 AI 编码智能体提供一个统一的、声明式的全局上下文，使得项目的工程契约不依赖于单一的工具。
定义智能体的角色职责、安全防线
- 角色：全栈工程师、测试专家、xxxxx
- 禁止执行的操作：不修改配置文件、不暴露敏感信息、xxxxx
定义难以从代码中推断的，或者容易遗忘的持久上下文
风格定义： 无歧义地规定当前项目使用的代码风格、语言版本、核心框架、依赖管理工具以及禁止使用的技术。例如，“使用 Python 3.11 和 FastAPI“。这种硬性规定能够有效阻断大模型在面对开放性问题时产生的技术栈偏移。
决策偏好： 记录历史迭代中积累的架构决策原因，以避免智能体重复提出已被团队否决的技术方案。例如，可以说明“我们选择在应用层处理数据聚合而非使用复杂的 SQL 视图，因为后者会导致数据库锁竞争，请在编写查询时遵循此约定”。
验证与反馈指南： 提供精确、可复制的命令行指令。智能体需要知道如何验证自己的工作，因此文件中必须包含具体的测试运行器指令（如 pytest tests/ -v）以及本地开发服务器的启动方式。
C. 约束的设计原则（少而稳 / 可演进）
避免“过度文档化”。过大的、事无巨细的规范文档反而是无情的Token消耗器、浪费掉大量上下文窗口资源，并可能使得关键指令被模型忽略。
少即是多（Less is More）
- 强通用性：具备适用于所有任务
- 摒弃边缘知识：仅适用于单一模块、罕见场景的要点们
渐进式披露（Progressive Disclosure）
- 路由
- 按需加载
例如，不在主文件中罗列数据库迁移的繁琐步骤，而是写明：“关于数据库迁移的详细规范与模板，请在执行相关任务前读取 docs/db_migration.md”。当智能体判定当前任务与数据库相关时，它会自动利用文件读取工具加载该特定文档，从而实现知识的按需加载。
E. 常见反模式与踩坑经验
| 常见约束反模式 | 现象与负面影响 | 纠正策略 |
|---|---|---|
| 模糊或自相矛盾 | 类似于“写出优雅的代码”等指令。这些词汇对机器推理有些用，但意义不大，只会徒增 Token 消耗量并引发幻觉。 | 具体的、可执行。 例如：“在所有外部 API 调用的返回点必须使用 try-catch 捕获异常，并使用标准的 ApiResponse DTO 对象结构进行错误信息构建”。 |
| 上下文腐化 | 随着业务演进，团队的真实规范已发生改变，但 CLAUDE.md 未做同步更新。这导致智能体基于过时的规范去重构新代码，制造出架构冲突。 | “文档即代码”，将 CLAUDE.md 视作与系统核心源码同等重要的活文档。要求架构变更必须伴随约束文件的同步修改。 |
| 滥用自动生成功能 | 在未充分理解项目结构的情况下，滥用 /init 命令让智能体自动生成约束文档并盲目信任，导致产生一个充满泛泛之谈的低质量上下文起点。 | 不可盲目信任，需要对项目进行必要的了解、对文档进行review和修正。 |
| 过多的代码格式化细节 | 在 CLAUDE.md 中写入大量关于缩进空格数、括号换行位置的细枝末节规则。LLM 处理此类确定性的字符串格式化既昂贵又缓慢，且容易出错。 | 依然将格式化与静态检查任务交还给确定性底层工具。让 LLM 逐步处理工具反馈的格式问题即可。 例如：“代码修改完成后，先执行 npm run lint:fix” |
III. 能力扩展：Claude 的工具化与系统化
为了应对复杂的系统级工程挑战，需要打破智能体被限制在终端沙盒中的孤岛状态。 随着迭代，目前 Claude Code 的生态系统有三大核心扩展基础设施：MCP、Skills 和 Plugins。
A. MCP —— 与外部世界交互的通用协议
模型上下文协议（Model Context Protocol, MCP）是一个开源的标准通信协议，其核心使命是为大语言模型提供标准化、安全且可扩展的外部数据管道与操作执行层。如果没有接入 MCP，Claude Code 仅仅是一个强大的本地文本处理器，它无法查询云端实时数据，无法操作无头浏览器进行页面视觉校验等等。
工作原理与底层传输架构
MCP 采用客户端-服务端（Client-Server）架构模式，通信基于轻量级的 JSON-RPC 格式。Claude Code 在此架构中充当高权限客户端，通过标准化的传输层机制与各类 MCP Server 进行实时数据交换。
成本陷阱与加载优化机制
MCP 的引入带来了强大的能力，但也伴随了一个不可忽视的负担：上下文膨胀（Context Bloat）。
由于 MCP 协议的特性，所有已连接服务器提供的工具定义及其复杂的 JSON Schema，默认会在每次会话启动时全量加载进大模型的系统提示词中。这些工具的定义描述可能会在毫无察觉的情况下消耗掉大量的初始上下文窗口，导致后续的推理能力严重退化。
为了解决这个问题，Claude Code 引入了“工具搜索（Tool Search）”与“延迟加载（Lazy Loading）”机制。该机制通过内部算法，默认将初始加载的工具控制在上下文总量的 10% 以下，而将那些并非立即可用的长尾工具进行索引化处理。只有当模型在推理过程中主动判定需要调用特定领域的工具时，才会实时将该工具的完整 Schema 抓取并加载到当前工作记忆中。同时，对于外部 API 返回的海量数据（如超长的 Sentry 错误日志），系统默认施加了 10,000 Tokens 的截断限制，开发者必须通过环境变量（如 MAX_MCP_OUTPUT_TOKENS）对其进行精细的显式管控。
B. Skills —— 可复用的能力模块
Skills 是极度灵活且结构化的 Markdown 文件夹集合，负责将特定的领域专家知识、复杂操作的业务逻辑流以及冗长的提示词模板封装为可复用的能力模块。
Skill 的结构解析
每个自定义 Skill 的核心枢纽是一个强制要求的 SKILL.md 文件。该文件由两个职责分明的区块组成：
YAML Frontmatter（元数据与控制层） 位于文件顶部的配置块，直接决定了该技能的被动触发逻辑与权限边界。核心配置项包括：
- name：定义供开发者手动调用的斜杠命令，如 /audit-security
- description：向大模型提供的语义线索，模型会据此在后台默默评估当前对话上下文是否契合该技能的调用条件，从而实现“自动触发”
- disable-model-invocation：关键的安全配置，若设为 true，则禁止模型自作主张调用该技能，强制要求人类显式输入命令触发，这在诸如 /deploy-to-prod 等高危操作中是必选项
- allowed-tools：授权该技能在后台运行时，可以免除人类二次确认直接调用的底层系统工具集合，如只读模式的文件检索
指令内容与动态上下文注入（Markdown 逻辑层） 文件的下半部分包含了传授给模型的具体操作步骤、数据处理模板以及验证逻辑。
- 动态参数注入。开发者可以通过 $ARGUMENTS 占位符捕获命令行的后续输入，
- ! command 的前缀语法，在技能执行前运行底层的 Shell 脚本（例如先执行 git diff），并将脚本的实时标准输出流作为动态文本嵌入到传递给模型的指令上下文中。
场景适应性与子智能体编排
Skills 的能力远不止于提供静态文本参考。通过在 Frontmatter 中配置 context: fork 声明，一个 Skill 能够实例化出一个带有完全独立且隔离的上下文环境的子智能体（Subagent）。例如，当主会话正在处理繁杂的业务逻辑重构时，开发者可以触发一个名为 /security-review 的 Skill。该 Skill 会立刻在后台“分叉（Fork）”出一个专门配置了代码审计工具、拥有完整原始上下文但不受当前对话冗余信息干扰的独立代理。这个子代理会在后台默默执行静态安全扫描、依赖漏洞排查，并在完成所有复杂分析后，将一份精炼的审计报告无缝汇总并回传给主进程的对话流中。这种并行处理与职责单一原则（SRP）的引入，彻底改变了人机协同的工作模式。
C. Plugins —— 面向场景的功能封装
随着个人工程经验的积累，开发者往往会针对不同的技术栈沉淀出大量的自定义 Skills、本地 MCP 服务器配置以及自动化生命周期钩子（Hooks）。单纯依赖文件系统的散装堆砌，将导致跨项目的配置难以同步与维护。Plugins（插件）系统应运而生，它提供了最高级别的“模块化打包与生态分发层”。
一个标准的 Plugin 能够将一组逻辑强相关的特征集合——包括深度的业务 Skills、拦截代码提交的 Linter Hooks、特定任务的 Subagents 配置，以及连接企业私有数据的 MCP 服务器——紧密捆绑成一个单一的、版本化的可安装单元。例如，一个“前端重构与效能插件”可能内部封装了：
一个负责将 Figma 设计稿转换为 AST 树的官方 Figma MCP 服务器。
一个包含了组件库规范与 CSS 命名最佳实践的 SKILL.md。
一个在模型执行文件写入前，自动调用外部 Prettier 格式化器的预处理 Hook。
D. 三者的边界与协作关系
| 特性维度 | MCP | Skills | Plugins |
|---|---|---|---|
| 核心定位 | 连接外部服务协议 | 知识和工作流模块 | 跨环境的统一打包 |
| 解决的核心痛点 | 突破大语言模型的本地沙盒隔离，赋予其获取外部实时动态数据和操作现实世界系统的能力 | 告诉 Claude 如何使用工具完成任务，并消除开发者重复撰写提示词的劳动 | 将多个 Skill/MCP 等组合成一个安装单元，用于跨项目分发 |
❓「什么时候该用 MCP，什么时候该写 Skill，什么时候做 Plugin？」
需要接入外部数据源或操作： MCP Server / Skill 皆可
需要实现可复用的内部流程或知识：Skill better
需要在多个仓库或团队间共享一整套功能：将这些 Skills/MCP 封装为一个 Plugin 分发。
IV. 文档驱动
文档不再是代码编写完成后的“事后补全”或单纯的合规性产物，而是驱动代码生成的源头指令。 本质上，大型语言模型（LLM）的编程能力取决于上下文的质量。与其每次在对话框中费力地敲入几百字的临时指令，不如将需求、逻辑和约束固化为文档。文档工程就是最高效的 Prompt Engineering。 维护良好的文档，实际上是在为 Claude 构建一个外部的“长时记忆库”。
A. 关键的工程文档
PRD (产品需求文档) 明确业务目标、核心用户流程（User Flows）及验收标准（Acceptance Criteria）。这是 Claude 的“任务书”，详细的边缘情况描述（Edge Cases），更能减少代码逻辑漏洞。
数据模型 定义数据库模型（Schema）、核心类/模块设计图及数据流向。这是“施工图纸”，防止它在实现功能时引入不符合项目架构的代码或错误的依赖关系。
技术方案 技术架构选型、依赖组件的选用、同步/异步的选择、外部服务和中间件的引用等。
接口文档 规范请求/响应的 Content-Type、JSON 结构、字段类型及错误码定义。这能让 Claude 准确生成 Mock 数据和前后端对接代码，避免因字段拼写错误或类型不匹配导致的低级 Bug。
测试方案 列出关键测试场景、输入数据样本及预期输出。这不仅是 QA 的指南，更是 Claude 编写自动化测试脚本（如 Pytest/Jest）的直接依据，实现测试驱动开发（TDD）。
工程计划 将大需求拆解为分步实施的 Task List（如：第一步建表，第二步写 Service，第三步写 UI）。这有助于 Claude 在有限的上下文窗口中分批次、高质量地完成任务，并逐步追踪，避免因任务过大导致“注意力涣散”。
B. 可选的说明文档
决策记录 (ADR) 记录历史架构决策的背景与原因（例如“为什么我们选择了 RabbitMQ 而不是 Kafka”）。这能充当 Claude 的“历史记忆”，防止它自作聪明地重构掉经过深思熟虑的代码逻辑。
领域字典 (Domain Dictionary) 统一业务术语的命名与定义（例如明确区分“用户 User”与“客户 Customer”的代码含义）。这能消除语义歧义，确保 Claude 生成的变量命名准确反映业务意图，避免概念混淆。
V. 设计哲学：把 Claude 当成“工程成员”
A. 不要指望一次 Prompt 解决一切
Claude Code 是对话式工具，不应寄希望于一次性提示完成所有工作。
“Claude Code 是对话式的。您不需要完美的提示。从您想要的开始，然后细化”。
换句话说，我们可以先提出一个粗略需求，让 Claude 开始行动；若第一次尝试不尽如人意，再通过额外反馈和指令迭代改进。当 Claude 偏离目标时，只需打断它并提供纠正，它就会调整方法继续工作。这种迭代式交互类似于与一位同事配合，让 Claude 在每一步获得反馈，从而更准确地满足需求。
B. 约束 -> 提示 -> 技巧
在使用 Claude 时，预先设定的约束比临时提示更为重要。正确的策略是提供稳定、结构化、可执行的上下文，让 Claude 在每个会话都遵循同样的指导，而不是依靠复杂提示“诱导”模型。简言之，与其用花哨的技巧应付一次性任务，不如用清晰的约束构建长期有效的合作基础。
C. 可维护性比聪明更重要
Claude 尽管智能，但其上下文资源终究有限。随着对话变长，上下文窗口会占满，性能会下降。因此，在项目中优先考虑可维护性和一致性远比追求模型“聪明”更重要。我们应遵循固有习惯，通过编写自动测试、使用 Hooks 进行自动化验证来保证结果正确，而不是想方设法让模型一次性输出正确答案。将更多注意力放在搭建可靠的工作流（如持续集成、代码规范检查）上，而非试图绕过模型限制，这样才能真正提高生产力。