1
Claude Code 不是代码补全，而是工程代理运行时
Claude Code 不是代码补全，而是工程代理运行时 TL;DR： Claude Code 的价值不在于"多写几行代码"，而在于把模型放进一个能读仓库、改文件、跑命令、接工具、受权限约束的执行环境。把它当工程代理运行时来配置和治理，而不是 IDE 补全插件来用。 定位：为什么"更强的 ChatGPT"是个错误框架...
vibecoding更新于
claude code 工程化实战
把claude code 用在真正的工作环境中
34 篇文章0 人订阅 创建
专栏简介
适合技术人，对claude code 有一定了解的
文章目录
2
你真正要解决的是上下文搬运、验证缺失和权限失控
你真正要解决的是上下文搬运、验证缺失和权限失控 TL;DR： AI Coding 在真实项目中的失败，几乎不是模型能力不足，而是三个工程问题的叠加：上下文不完整导致误判、生成结果缺乏验证链路、权限边界过宽导致事故半径扩大。Claude Code 工程化的起点，是把这三个问题显式化并配好对应机制。 为什么"模型更强了"...
3
安装、登录、权限模式和第一个真实仓库任务
安装、登录、权限模式和第一个真实仓库任务 TL;DR： 安装 Claude Code 后的第一次操作不应该是让它写代码。正确的顺序是：安装认证 → 配置权限 → 验证项目上下文是否充分 → 做一个低风险的诊断任务。跳过前两步直接上功能的团队，后面花在修复 AI 误操作上的时间是前期配置的 8 10 倍。 安装与认证...
4
项目地图：让 Claude Code 读懂目录、命令和边界
项目地图：让 Claude Code 读懂目录、命令和边界 TL;DR： 项目地图不是目录树打印。它是一份结构化声明，告诉 Claude Code 哪些目录存在、各管什么、服务怎么调用、命令怎么跑、哪些东西不能碰。没有地图，Claude Code 靠搜索猜结构——猜错一次就是跨模块耦合的开始。 问题 新成员进项目会问...
5
CLAUDE.md：把团队规则写成机器可用上下文
CLAUDE.md：把团队规则写成机器可用上下文 TL;DR： CLAUDE.md 不是给人读的文档，是给模型读的工程规格。它控制 Claude Code 的行为边界，每次会话都被全量加载到上下文。写得好，省掉反复提醒；写得差，浪费 Token 还不生效。 CLAUDE.md 是工程规格，不是文档 大多数团队第一次写...
6
.claude/rules：把大规则拆成按路径加载的小规则
.claude/rules：把大规则拆成按路径加载的小规则 TL;DR： CLAUDE.md 每次会话全量加载，规则多了就变成噪声。.claude/rules/ 目录里的 Markdown 文件可以按路径匹配按需加载——编辑前端时只加载前端规则，改数据库时只加载数据库规则。 问题 一个 monorepo 里同时存在...
7
常用工作流：解释代码、修 Bug、补测试、写文档
常用工作流：解释代码、修 Bug、补测试、写文档 TL;DR： 解释代码、修 Bug、补测试、更新文档——四个高频低风险工作流。跑通这四个，等于验证了 CLAUDE.md、测试闭环和模块边界。跑不通就别做复杂任务。 为什么要从这四个工作流开始 团队引入 Claude Code 后最常见的错误：直接甩一个大需求过去，结...
8
Slash Commands：把一次性提示词变成团队命令
Slash Commands：把一次性提示词变成团队命令 TL;DR： Slash Commands 是 .claude/commands/ 里的 Markdown 文件，按需加载，用 $ARGUMENTS 参数化。它解决的是"第三次重复写同一段提示词"的问题——把高频、短流程的任务固化成版本化文件，消除提示词漂移，...
9
Skills 入门：什么时候该从命令升级为 Skill
Skills 入门：什么时候该从命令升级为 Skill TL;DR： Command 是一段可复用提示词，Skill 是一套结构化能力。当任务需要多步骤、外部资源、脚本执行或渐进式加载时，Command 已经不够用了——该升级。升级不是目的，解决 Command 无法承担的复杂性才是。 Command 和 Skill...
10
SKILL.md 结构：触发描述、步骤、资源和脚本
SKILL.md 结构：触发描述、步骤、资源和脚本 TL;DR： SKILL.md 是 Claude Code 的最小可执行能力单元。它的结构直接决定了三个结果：能否被正确触发、加载后能否正确执行、执行时 Token 消耗是否可控。写好 SKILL.md 不是写好提示词，是设计好一个可复用的操作规程。 SKILL.m...
11
渐进式披露：避免 Skill 一次塞爆上下文
渐进式披露：避免 Skill 一次塞爆上下文 TL;DR： 每个 token 进上下文都意味着一个 token 不可用于实际任务。500 行的 Skill 全量加载可消耗 8000+ token。正确做法：SKILL.md 只放触发和路由，模板、脚本、参考资料按需读取。 上下文预算问题 Claude Code 的上下...
12
Skill 评测：欠触发、误触发和执行失败怎么修
Skill 评测：欠触发、误触发和执行失败怎么修 TL;DR： Skill 写完不等于能用。三类核心故障——欠触发、误触发、执行失败——各有根因和修复路径。用 15 条评测集量化触发精度，用评分表量化输出质量，迭代三轮再上线。 问题 团队写完 SKILL.md 直接进生产。现象：有时 Claude 不加载 Skill...
13
Subagents 的本质：独立上下文里的专家助手
Subagents 的本质：独立上下文里的专家助手 TL;DR： Subagent 不是"更聪明的 Claude"。它是一块隔离的执行沙箱：独立上下文窗口、独立系统提示词、独立工具白名单。用来做"完成后汇报"的专门任务，而不是替代主会话做持续编辑。 问题 主会话在处理复杂项目时面临三重压力： 1. 上下文膨胀 。安全...
14
三类高价值 Subagent：探索、审查、测试
三类高价值 Subagent：探索、审查、测试 TL;DR： 最值得先做的 Subagent 是 explorer、reviewer、test runner。它们任务边界清楚，能独立工作，结果容易验证。不要一开始就创建十几个角色，先跑稳这三个。 问题 团队一开始常创建很多花哨角色：架构师、产品经理、性能专家、文档专家...
15
工具权限：只读审计代理为什么不能有写权限
工具权限：只读审计代理为什么不能有写权限 TL;DR： Subagent 的工具权限应该按任务最小化。审计、研究、测试诊断通常不需要写文件权限。权限升级应该基于失败证据，而不是预期需求。 问题 如果所有 subagent 都继承主会话全部工具，隔离上下文的收益会被权限风险抵消。一个只负责审查的代理不应该能改代码，一个...
16
并行探索：让多个代理独立研究再汇总
并行探索：让多个代理独立研究再汇总 TL;DR： 并行探索适合大任务的前期判断。让多个 subagent 分别研究不同方向，再由主会话整合方案。并行会增加总 token 消耗，但显著减少挂钟时间。关键前提：任务必须能拆成相互独立的问题。 问题 大型改造开始前，最耗时的是理解：哪些模块相关、现有模式是什么、风险在哪里、...
17
不该用 Subagent 的场景：共享细节和连续编辑
不该用 Subagent 的场景：共享细节和连续编辑 TL;DR： Subagent 不适合所有复杂任务。需要频繁共享细节、连续编辑同一批文件、上下文高度耦合的任务，留在主会话更稳。不是所有任务都值得隔离——有时候隔离本身就是成本。 问题 看到 Subagent 后，很容易把所有任务都拆出去。结果是多个代理重复读文件...
18
MCP 心智模型：外部系统不是复制粘贴，而是工具接口
MCP 心智模型：外部系统不是复制粘贴，而是工具接口 TL;DR： MCP 让 Claude Code 把外部系统当作结构化工具来调用，而不是让人类做中间搬运工。但 MCP 不是万能胶水——理解它的协议边界、工具定义模型和风险特征，才能判断什么该接、什么不该接。 为什么需要 MCP：复制粘贴的工程代价 没有 MCP...
19
第一个 MCP：GitHub Issue、PR 和代码上下文
第一个 MCP：GitHub Issue、PR 和代码上下文 TL;DR： GitHub MCP 是最适合作为第一个 MCP 接入的系统。它已经在开发者的日常工作流中，数据以读为主，权限可以精确分级，且 AI 辅助编码的核心上下文——issue、PR、代码、CI——都集中在这里。 为什么 GitHub 是第一个 MC...
20
数据库、监控和设计系统：高价值 MCP 场景
数据库、监控和设计系统：高价值 MCP 场景 TL;DR： GitHub MCP 建立基础后，高价值的下一步是接入那些减少"信息搬运瓶颈"的系统。每个场景有不同的权限模型、Token 消耗特征和风险等级。引入顺序应该由团队的实际工作流决定，而不是技术难度。 从 GitHub MCP 到多系统 MCP 的过渡 在接入...
21
MCP + Skill：让工具按团队 SOP 被正确使用
MCP + Skill：让工具按团队 SOP 被正确使用 TL;DR： MCP 提供"能做什么"，Skill 提供"应该怎么做"。只接 MCP 不写 Skill，等于给实习生一个 API key 但不给他操作手册——工具在手里，但流程在脑子里，而 AI 的脑子里没有你的团队流程。 为什么 MCP 单独使用效果有限 很...
22
MCP 风险：Token、越权、工具投毒和提示注入
MCP 风险：Token、越权、工具投毒和提示注入 TL;DR： MCP 把 Claude Code 接到真实系统，也把真实系统的攻击面带到了 AI 的推理链路中。六个威胁维度、对应防护策略和审计清单。这不是理论——每个威胁都有对应的真实事故。 为什么 MCP 风险需要专门讨论 Claude Code 的内置工具（R...
23
Hooks 入门：事件驱动的自动化和审计
Hooks 入门：事件驱动的自动化和审计 TL;DR： Hooks 是 Claude Code 的确定性控制层。模型负责推理，Hooks 负责在固定事件上记录、拦截、提醒和验证。它不是第二个 AI，而是纯脚本的规则引擎。 为什么需要 Hooks CLAUDE.md 可以写"不要修改 .env 文件"，但提示词约束本质...
24
PreToolUse：阻断危险命令和高风险文件写入
PreToolUse：阻断危险命令和高风险文件写入 TL;DR： PreToolUse 是 Claude Code 安全控制的核心关卡。它通过退出码 2 阻断工具调用，是唯一能物理阻止 AI 行为的机制。设计原则：只拦截明确危险的操作，不做复杂业务判断。 为什么 PreToolUse 是第一道防线 Claude Co...
25
PostToolUse / Stop：自动格式化、测试和结果记录
PostToolUse / Stop：自动格式化、测试和结果记录 TL;DR： 修改完成后的验证比修改本身更重要。PostToolUse 在工具执行后做增量验证，Stop 在会话结束时做全局验证。两者配合形成完整的验证闭环。 为什么需要执行后验证 Claude Code 修改文件后，默认行为是向用户展示修改结果并继续...
26
Subagent Hooks：给子代理注入上下文并收集结果
Subagent Hooks：给子代理注入上下文并收集结果 TL;DR： Subagent Hooks 管理多代理任务的边界。SubagentStart 在子代理启动前注入通用规则和输出约束，SubagentStop 在子代理结束后收集结论和审计信息。通用规则放 Hook，角色规则放 agent 配置文件。 问题：子...
27
Hook 设计原则：小、确定、可解释、可回滚
Hook 设计原则：小、确定、可解释、可回滚 TL;DR： Hook 是确定性治理层，不是第二个 Agent。四条硬性约束：小（代码 ≤ 50 行，复杂度评分 ≤ 20）、确定（同样 stdin → 同样退出码）、可解释（每个 exit 2 必须带规则编号和替代方案）、可回滚（可单独禁用，禁用即时生效）。违反任一条，...
28
Headless 模式：把 Claude Code 放进脚本
Headless 模式：把 Claude Code 放进脚本 TL;DR： Headless 模式用 p 参数把 Claude Code 从交互式终端工具变成可编排的自动化组件。适合批处理、CI/CD 集成、定期巡检和低风险只读任务。关键是控制提示词作用域、设定 max turns 上限、用 output forma...
29
GitHub Actions：PR Review、Issue Triage 和简单修复
GitHub Actions：PR Review、Issue Triage 和简单修复 TL;DR： GitHub Actions 把 Claude Code 接入团队协作流程。第一批场景应该是 review、triage、摘要和低风险修复，不是自动合并。配置关键是：触发条件过滤、权限最小化、提示词精确、输出格式约束...
30
CI 里的安全边界：Secrets、外部 PR、权限和审批
CI 里的安全边界：Secrets、外部 PR、权限和审批 TL;DR： 在 CI 里运行 Claude Code，最大风险不是生成错代码，而是权限配置错误导致 secrets 泄露、外部 PR 注入、workflow 被篡改或供应链攻击。每个风险都需要独立设计防护层。 问题 CI 环境天然连接仓库、token、se...
31
结构化输出：JSON Schema 与输出管道
结构化输出：JSON Schema 与输出管道 TL;DR： 自动化场景里，Claude Code 不能只输出自然语言。结构化输出通过 output format json 和 JSON Schema 约束，让后续脚本、CI 看板和审计系统能解析和动作化结果。关键不是让模型"输出 JSON"，而是设计 schema、...
32
Agent SDK：SDK 架构、集成模式与生产部署
Agent SDK：SDK 架构、集成模式与生产部署 TL;DR： Agent SDK 把 Claude Code 的 agent loop、工具系统、Hooks 和 MCP 从交互式终端搬到程序化接口。核心 API 围绕 Agent、Tool、Session 三个原语构建，通过 event stream 实现状态同...
33
Plugins：打包 Commands、Agents、Skills、Hooks 和 MCP
Plugins：打包 Commands、Agents、Skills、Hooks 和 MCP TL;DR： Plugin 是 Claude Code 能力的分发单元。它把 commands、agents、skills、hooks 和 MCP servers 打包成一个可安装、可版本化、可分发的整体。适合跨仓库、跨团队复...
34
组织级治理：版本、审计、评测、禁用和升级策略
组织级治理：版本、审计、评测、禁用和升级策略 TL;DR： 组织级 Claude Code 落地不是"全员装工具"。它是管理七类治理对象的版本、权限、审计、评测、禁用和升级。没有治理框架的规模化推广，等于把生产环境的钥匙交给一个你无法审计的系统。 问题 个人使用 Claude Code，风险由个人承担。组织使用时，风...