1. 项目概述我如何为Claude Code打造专属“缰绳”如果你也和我一样在日常开发中重度依赖Claude Code这类AI编程助手那你肯定经历过这样的时刻每次开启一个新项目都要不厌其烦地重复一遍项目规则每次开发新功能都要手动引导AI完成“设计-实现-验证”的循环更别提那些因为一时疏忽差点把.env文件提交到仓库或者手滑执行了git push --force main的惊魂瞬间。我们使用AI是为了提升效率但如果没有一套好的“工作框架”反而会陷入低效的重复劳动和潜在的风险中。这就是“缰绳工程”要解决的问题。它不是一个简单的提示词优化技巧而是一套完整的、可自动化的系统框架用来定义和约束AI助手在你项目中的工作方式。你可以把它想象成给一匹充满力量的骏马AI套上的一套精良的马具Harness不是为了束缚它而是为了让它能更安全、更高效、更精准地朝着你设定的目标奔跑。这套系统完全基于Claude Code的官方功能如自定义命令、钩子构建不涉及任何非公开接口核心目标就一个把那些你每次都要手动交代的、容易出错的、繁琐的流程固化成一个“开机自启”的自动化工作流。经过一段时间的实践我的开发流程发生了肉眼可见的变化启动新项目从需要15分钟交代背景变成一行命令功能开发从随性的口头指令变成了标准化的流水线甚至一些我以前因为“麻烦”而经常跳过的步骤比如写设计文档、做技术调研现在都被系统强制纳入了流程。最有趣的是我最初搭建这套系统是因为“懒”但结果却让我变成了一个更严谨、更有条理的开发者。2. “缰绳工程”核心三要素解析一套完整的“缰绳”系统由三个层次分明、各司其职的组件构成规则、命令和钩子。它们的关系可以类比于法律体系规则是宪法定义了根本原则命令是具体的法律法规指导如何做事钩子则是执法系统确保法律被遵守并阻止违法行为。2.1 规则项目的“根本大法”规则层是整个系统的基石其载体是位于项目根目录的CLAUDE.md文件。这个文件不是对AI的“建议”而是它在这个项目中必须始终遵守的“最高指令”。规则文件的核心作用定义技术栈与架构约束明确项目使用的框架、语言版本、包管理器、代码风格如ESLint/Prettier规则、目录结构规范等。这确保了AI生成的代码与项目现有生态无缝集成。设定绝对禁令列出绝对不能做的事情。例如“禁止向main分支进行强制推送”、“禁止提交包含敏感信息的文件如.env,*.pem”、“禁止使用已弃用的API或库”。确立团队或个人工作流说明分支策略如Git Flow, GitHub Flow、提交信息规范如Conventional Commits、代码审查流程等。注意一个高效的CLAUDE.md应该是具体、可执行的。避免使用“写出高质量的代码”这类模糊表述取而代之的是“函数长度不超过50行”、“必须为新增的公共API编写JSDoc注释”、“组件使用TypeScript且必须定义Props接口”。2.2 命令可复用的“工作剧本”命令层对应的是保存在.claude/commands/目录下的Markdown文件。每个文件封装了一个特定的、复杂的任务流程。你可以把它理解为针对不同场景编写好的“剧本”或“宏”当AI执行这个命令时它会按照剧本一步步推进。命令的设计哲学标准化复杂流程将“设计一个新功能”或“修复一类特定Bug”这种多步骤任务固化下来避免每次都要重新描述。实现角色切换这是命令系统最强大的地方。通过不同的命令你可以让同一个Claude实例在“规划师”、“生成器”、“评估师”等角色间无缝切换每个角色专注于流程中的一个环节有效避免了“自我验证”的盲区。提升交互效率从冗长的自然语言描述变为简洁的/workflow “用户登录功能”减少了歧义提高了指令的准确性和可重复性。在我的设置中核心命令包括/workflow功能开发总指挥按顺序调用其他命令。/plan-and-spec扮演“规划师”负责需求拆解、技术可行性调研和输出设计文档。/tdd扮演“生成器”以测试驱动的方式实现功能。/verify扮演“评估师”对比设计文档与实现进行验收。/commit处理代码提交与合并。2.3 钩子自动执行的“安全卫兵”钩子层是系统的“免疫系统”它通过settings.json配置在AI执行特定动作如调用Bash工具前后自动触发外部脚本。钩子不是可选的只要条件匹配它就会强制执行。钩子的核心价值主动防御在错误发生之前进行拦截。这是它与事后靠人眼检查的本质区别。无感集成一旦配置好开发者无需额外记忆或操作安全策略自动生效。扩展性强理论上任何可以通过脚本判断的逻辑都可以做成钩子如检查代码中是否包含调试语句、是否引入了未经许可的依赖等。我配置的最关键的一个钩子是PreToolUse它在Claude每次试图执行Bash命令前都会先运行一个block-dangerous.sh脚本。这个脚本目前主要做两件事拦截对main分支的强制推送任何包含push --force main或push main --force模式的命令都会被立即终止。阻止提交.env文件任何试图将.env文件加入git暂存区的操作也会被阻止。#!/bin/bash INPUT$(cat) # 阻止强制推送到main分支 if echo $INPUT | grep -q push.*--force.*main\|push.*main.*--force; then echo 错误禁止强制推送至main分支。请考虑使用--force-with-lease或创建合并请求。 2 exit 2 fi # 阻止提交.env文件 if echo $INPUT | grep -q git add.*\.env\b; then echo 警告检测到试图添加.env文件。请确认该文件已加入.gitignore或使用环境变量。 2 exit 2 fi exit 0这个脚本的退出码2是关键它告诉Claude Code该命令被明确阻止。与之配套的settings.json配置如下{ hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: bash ~/.claude/hooks/block-dangerous.sh }] }] } }3. 系统架构与自动化搭建实战理解了三大组件后我们来看如何将它们组织成一个即开即用的系统。我的目录结构遵循“全局共享”与“项目独有”分离的原则最大程度实现复用。3.1 全局与项目目录结构详解~/.claude/ # 【全局目录】机器上所有项目共享一次性设置 ├── commands/ # 全局命令 │ ├── init-harness.md # 核心自动初始化项目缰绳 │ ├── new-project.md # 从想法到项目脚手架 │ └── session-resume.md # 会话恢复重载上下文 ├── hooks/ # 全局钩子脚本 │ └── block-dangerous.sh # 危险命令拦截器 └── settings.json # 钩子配置文件 your-project/ # 【项目目录】每个项目独立 ├── CLAUDE.md # 项目专属规则由init-harness生成草案 ├── progress.md # 当前任务进度追踪 ├── dev-log.md # 开发日志按功能记录 ├── docs/ # 设计文档、API说明等 ├── screenshots/ # UI截图、效果图存档 └── .claude/ # 项目级命令可覆盖全局 └── commands/ ├── workflow.md ├── plan-and-spec.md ├── tdd.md ├── ui-ux.md ├── verify.md └── commit.md设计思路全局区~/.claude存放放之四海而皆准的配置。比如拦截危险命令的钩子、创建新项目的模板流程这些逻辑在任何项目上都通用只需设置一次。项目区项目内/.claude存放与当前项目强相关的内容。比如针对本项目技术栈Next.js Supabase的workflow命令细节或者项目特定的代码生成规则。项目区命令可以覆盖全局区的同名命令实现定制化。3.2 一键初始化/init-harness 命令剖析这是整个系统的“点火开关”。无论是一个空文件夹还是一个已有项目你只需要输入/init-harness它就会在只读模式下分析项目然后自动生成全套配置。整个过程没有中间确认提示分析完直接生成非常流畅。步骤拆解步骤1项目分析只读零侵入这个阶段AI会像一位侦探一样扫描你的项目但绝不修改任何文件。它主要查看package.json确定技术栈如Next.js 15, TypeScript, Tailwind CSS。目录结构3层深度了解是App Router还是Pages Router是否有src目录模块划分方式。git log --oneline -20分析团队的提交习惯和规范是否使用feat/fix前缀。git branch -a了解分支策略是Git Flow还是简单的主干开发。.env.example推断集成了哪些外部服务如Supabase, Stripe, Resend。分析完成后它会输出一份简洁的报告并据此决定需要生成哪些命令文件。[项目分析报告] - 技术栈: Next.js 15 / TypeScript / Supabase / Tailwind CSS - 目录结构: App Router 无src/目录功能模块化组织 - 提交规范: 使用 feat/fix/refactor 前缀 - 分支策略: feature/* 分支直接合并至 main - 集成服务: Supabase (认证/数据库), Resend (邮件), Lemon Squeezy (支付) - 待生成命令: workflow, plan-and-spec, tdd, ui-ux, verify, commit步骤2生成 CLAUDE.md 草案基于分析结果AI不会套用一个空模板而是生成一个填充了具体内容的CLAUDE.md。例如它会自动加入“本项目使用Next.js 15的App Router所有组件应为React Server Components除非显式使用‘use client’。”“国际化所有用户可见文本必须使用next-intl从/messages/目录获取禁止硬编码字符串。”“绝对禁止强制推送至main分支提交.env或任何包含API_KEY、SECRET字样的文件。”步骤3 4生成命令与项目文件在项目的.claude/commands/目录下生成全套命令文件workflow.md,plan-and-spec.md等。同时在项目根目录创建progress.md任务进度、dev-log.md开发日志以及docs/和screenshots/文件夹。步骤5检查并补全全局文件最后检查~/.claude/下的全局命令和钩子是否存在如session-resume.md,block-dangerous.sh。如果不存在则创建它们如果已存在则保留原样。这确保了系统的完整性。实操心得init-harness生成的是优秀的起点但绝非终点。你必须手动审阅并完善它生成的CLAUDE.md加入那些只有你才知道的细节比如公司的内部库命名规范、特定的部署环境变量命名规则、代码审查的特定检查点等。把它当成一个帮你完成了80%工作的助手剩下的20%关键细节需要你亲自把关。4. 核心工作流从规划到交付的自动化流水线系统搭建好后日常的功能开发就变成了运行一条命令。以开发一个“用户反馈自动分类”功能为例你只需要输入/workflow “feedback auto-classify feature”。4.1 工作流引擎/workflow 命令全流程这条命令会触发一个完整的、自动化的流水线状态评估读取progress.md和最近的git日志理解项目当前所处阶段。分支创建自动创建并切换到新分支如feature/feedback-auto-classify。规划与设计调用/plan-and-spec命令。AI切换至“规划师”角色进行技术调研、可行性分析并输出详细的设计文档docs/spec-feedback-auto-classify.md。测试驱动开发调用/tdd命令。AI切换至“生成器”角色根据设计文档以“红-绿-重构”的循环进行编码实现。验证与验收调用/verify命令。AI切换至“评估者”角色将实际代码与设计文档逐项对比检查功能完整性、边界情况、i18n覆盖等并运行测试。提交与合并调用/commit命令。生成符合规范的提交信息推送分支并在设置允许的情况下合并回主分支。循环反馈如果第5步验证失败工作流会自动跳回第4步/tdd让“生成器”根据评估反馈进行修复然后再次验证直到通过。这个流程的强大之处在于角色的强制分离。让同一个AI在“规划”、“实现”、“验证”三个角色间切换相当于在团队中引入了“分权制衡”的机制能有效减少由于思维定势导致的盲点。4.2 角色扮演规划师、生成器与评估者的协同规划师 (/plan-and-spec)它的首要任务是“事实核查”。在写一行代码之前它会先问“这个想法真的可行吗”例如在实现“反馈聚类”功能时规划师会搜索确认pgvector扩展在项目使用的PostgreSQL版本中是否可用并核实其安装命令。调研Voyage AI或OpenAI的嵌入API确认其调用方式、费率、速率限制。查找类似的实现案例评估计算复杂度和性能。最终输出一份包含数据流图、API接口定义、数据库Schema变更和潜在风险的设计文档。生成器 (/tdd)它严格遵循设计文档进行实现。我特别在命令中加入了“模拟数据注入”的步骤每完成一个UI组件就要求AI生成并注入符合业务逻辑的模拟数据让界面立刻看起来是“活的”。这借鉴了之前手动截图验证UI的经验现在将其自动化了。如果实现过程中发现设计有误或可以优化生成器会立即更新docs/spec-*.md文件并说明变更原因确保设计与代码始终同步。评估者 (/verify)它的检查清单远不止“代码能否运行”。它会功能对比逐项核对设计文档中的需求点是否在代码中实现。完整性检查检查所有用户可见的字符串是否都已提取到国际化文件。错误处理验证API调用、用户输入等是否有适当的错误边界和用户提示。代码质量运行项目的lint和type check确保符合规范。构建检查尝试运行npm run build确保生产构建能通过。一次真实的成功拦截在开发上述聚类功能时生成器完成了核心的clustering.ts188行代码。评估者在验收时发现设计文档中要求的“余弦相似度阈值可配置”功能虽然相关UI控件已存在但后端处理逻辑中缺少了对该阈值参数的读取和应用。这个疏忽被成功捕获并在合并前得以修复。如果没有评估者这个独立角色这种“看似有实则无”的Bug很可能逃过审查直到上线后才被发现。5. 安全与效率的基石钩子配置与全自动模式5.1 安全钩子的深度配置前面提到的block-dangerous.sh是最基础的防线。在实际中你可以根据团队痛点无限扩展这个脚本。例如增加以下检查#!/bin/bash INPUT$(cat) # ... 原有的 force push 和 .env 检查 ... # 阻止安装来源不明的包例如从非官方源或特定黑名单 if echo $INPUT | grep -q npm install.*\\(example-malicious-package\\|--registryhttp://可疑源\\); then echo 安全警告检测到可能安装不安全的包。请从官方npm仓库安装。 2 exit 2 fi # 阻止删除特定重要目录或文件防误操作 if echo $INPUT | grep -Eq rm -rf.*\\(/src/app\\|/prisma/schema.prisma\\); then echo 危险操作试图删除关键目录或文件。请确认操作意图。 2 exit 2 fi # 阻止向生产环境数据库执行破坏性操作通过连接字符串判断 if echo $INPUT | grep -q psql.*DATABASE_URL.*prod.*\\(DROP\\|TRUNCATE\\); then echo 致命错误禁止对生产数据库执行DROP/TRUNCATE操作 2 exit 2 fi exit 0将这些检查集成到PreToolUse钩子中就等于为你的终端加上了一道“防火墙”。它不会影响正常的开发命令但会在你或AI即将执行高风险操作时紧急刹车。5.2 拥抱全自动模式--dangerously-skip-permissionsClaude Code有一个--dangerously-skip-permissions标志。启用后AI在执行需要确认的操作如运行安装命令、写入文件时将不再询问“是否继续”而是直接执行。很多人对这个标志望而生畏但关键在于危险的不是标志本身而是在没有安全措施的情况下使用它。我的工作流是先建立缰绳尤其是钩子再启用全自动模式。当block-dangerous.sh等钩子就位后全自动模式就成了效率的加速器。你可以放心地启动/workflow然后去喝杯咖啡回来时AI已经完成了从分支创建、编码、测试到提交合并的全过程。此时钩子扮演了“自动驾驶中的安全员”角色在关键时刻接管控制权防止系统驶入悬崖。5.3 上下文无缝恢复/session-resume开发中途Claude Code会话超时或中断是常事。传统的做法是你需要重新打开项目然后花时间向AI复述“我们刚才在做什么做到了哪一步接下来要干嘛。”有了/session-resume命令这个过程被极大简化。这个命令会读取progress.md的最后30行了解整体任务进度。读取dev-log.md的最后30行获取最近的开发细节。执行git log --oneline -10和git status掌握代码库的最新状态。综合以上信息生成一份清晰的摘要“我们正在开发‘反馈分类’功能。已完成聚类算法后端APIcommit abc123当前位于feature/feedback-auto-classify分支。下一步是根据docs/spec-*.md第3节实现前端管理界面。”这与你手动编写的CLAUDE.md维护规则形成了完美互补一个维护“静态规则”一个恢复“动态状态”。6. 常见问题与实战避坑指南Q1: 使用/init-harness后我就不需要自己写CLAUDE.md了吗A1大错特错。/init-harness生成的是一个优秀的、基于项目分析的草案。但它无法知道你们团队内部的特殊约定、特定库的怪异用法、或者部署环境的细微配置。你必须将其作为起点然后手动补充这些关键信息。正确的流程是运行命令 - 审查生成的文件 - 补充团队特有的规则和禁忌。Q2: 我必须每次都使用/workflow这种复杂的命令吗A2完全不必。这套系统的设计哲学是“该繁则繁该简则简”。对于修一个拼写错误、调整一个CSS样式这种小事你完全可以直接用自然语言告诉AI“把按钮的颜色从蓝色改成绿色。” 命令系统是为那些需要严谨流程的功能级开发准备的。钩子是始终运行的“后台守护进程”而命令是随取随用的“特种工具”。Q3: 这个结构能用于团队协作吗A3可以但需要调整。我目前的设置是为个人或小团队“直接合并到main”的快速迭代模式优化的。在严格的团队环境中你需要修改CLAUDE.md明确代码审查要求、PR模板、CI/CD触发条件。修改/commit命令将其从“直接合并”改为“创建Pull Request并等待审查”。可能需要在钩子中增加团队规范检查例如提交前必须通过所有CI检查。将全局配置~/.claude通过版本控制如一个内部模板仓库共享给所有团队成员确保一致性。Q4: 如何开始搭建自己的“缰绳”感觉无从下手。A4我建议采用迭代式搭建从最痛的点开始第一步立即行动创建你的~/.claude/hooks/block-dangerous.sh和settings.json。哪怕只实现拦截git push --force main这一条你也立即获得了一份巨大的安全感。第二步核心规则为你最常开发的项目类型如Next.js项目手动编写一个高质量的CLAUDE.md模板。这可能是投入回报比最高的部分。第三步自动化基于这个模板创建一个简化版的/init-harness命令让它能自动创建项目目录和基础文件。第四步优化流程当你发现某个开发步骤比如“写设计文档”总是被跳过或做不好时就为它创建一个专门的命令如/plan-and-spec把最佳实践固化进去。持续迭代每当你心想“要是AI能自动做X就好了”的时候就去看看能否通过新增或修改一个命令/钩子来实现它。最大的陷阱是试图一开始就设计一个完美、复杂的系统。这会导致你迟迟无法开始或者系统过于笨重而被弃用。记住“缰绳工程”的本质不是构建一个完美的框架而是将令你烦恼的事情一个一个地自动化掉。从一个钩子、一个命令开始让它先跑起来在使用的过程中你自然会知道下一步该优化哪里。
为AI编程助手构建自动化工作流：规则、命令与钩子实践
1. 项目概述我如何为Claude Code打造专属“缰绳”如果你也和我一样在日常开发中重度依赖Claude Code这类AI编程助手那你肯定经历过这样的时刻每次开启一个新项目都要不厌其烦地重复一遍项目规则每次开发新功能都要手动引导AI完成“设计-实现-验证”的循环更别提那些因为一时疏忽差点把.env文件提交到仓库或者手滑执行了git push --force main的惊魂瞬间。我们使用AI是为了提升效率但如果没有一套好的“工作框架”反而会陷入低效的重复劳动和潜在的风险中。这就是“缰绳工程”要解决的问题。它不是一个简单的提示词优化技巧而是一套完整的、可自动化的系统框架用来定义和约束AI助手在你项目中的工作方式。你可以把它想象成给一匹充满力量的骏马AI套上的一套精良的马具Harness不是为了束缚它而是为了让它能更安全、更高效、更精准地朝着你设定的目标奔跑。这套系统完全基于Claude Code的官方功能如自定义命令、钩子构建不涉及任何非公开接口核心目标就一个把那些你每次都要手动交代的、容易出错的、繁琐的流程固化成一个“开机自启”的自动化工作流。经过一段时间的实践我的开发流程发生了肉眼可见的变化启动新项目从需要15分钟交代背景变成一行命令功能开发从随性的口头指令变成了标准化的流水线甚至一些我以前因为“麻烦”而经常跳过的步骤比如写设计文档、做技术调研现在都被系统强制纳入了流程。最有趣的是我最初搭建这套系统是因为“懒”但结果却让我变成了一个更严谨、更有条理的开发者。2. “缰绳工程”核心三要素解析一套完整的“缰绳”系统由三个层次分明、各司其职的组件构成规则、命令和钩子。它们的关系可以类比于法律体系规则是宪法定义了根本原则命令是具体的法律法规指导如何做事钩子则是执法系统确保法律被遵守并阻止违法行为。2.1 规则项目的“根本大法”规则层是整个系统的基石其载体是位于项目根目录的CLAUDE.md文件。这个文件不是对AI的“建议”而是它在这个项目中必须始终遵守的“最高指令”。规则文件的核心作用定义技术栈与架构约束明确项目使用的框架、语言版本、包管理器、代码风格如ESLint/Prettier规则、目录结构规范等。这确保了AI生成的代码与项目现有生态无缝集成。设定绝对禁令列出绝对不能做的事情。例如“禁止向main分支进行强制推送”、“禁止提交包含敏感信息的文件如.env,*.pem”、“禁止使用已弃用的API或库”。确立团队或个人工作流说明分支策略如Git Flow, GitHub Flow、提交信息规范如Conventional Commits、代码审查流程等。注意一个高效的CLAUDE.md应该是具体、可执行的。避免使用“写出高质量的代码”这类模糊表述取而代之的是“函数长度不超过50行”、“必须为新增的公共API编写JSDoc注释”、“组件使用TypeScript且必须定义Props接口”。2.2 命令可复用的“工作剧本”命令层对应的是保存在.claude/commands/目录下的Markdown文件。每个文件封装了一个特定的、复杂的任务流程。你可以把它理解为针对不同场景编写好的“剧本”或“宏”当AI执行这个命令时它会按照剧本一步步推进。命令的设计哲学标准化复杂流程将“设计一个新功能”或“修复一类特定Bug”这种多步骤任务固化下来避免每次都要重新描述。实现角色切换这是命令系统最强大的地方。通过不同的命令你可以让同一个Claude实例在“规划师”、“生成器”、“评估师”等角色间无缝切换每个角色专注于流程中的一个环节有效避免了“自我验证”的盲区。提升交互效率从冗长的自然语言描述变为简洁的/workflow “用户登录功能”减少了歧义提高了指令的准确性和可重复性。在我的设置中核心命令包括/workflow功能开发总指挥按顺序调用其他命令。/plan-and-spec扮演“规划师”负责需求拆解、技术可行性调研和输出设计文档。/tdd扮演“生成器”以测试驱动的方式实现功能。/verify扮演“评估师”对比设计文档与实现进行验收。/commit处理代码提交与合并。2.3 钩子自动执行的“安全卫兵”钩子层是系统的“免疫系统”它通过settings.json配置在AI执行特定动作如调用Bash工具前后自动触发外部脚本。钩子不是可选的只要条件匹配它就会强制执行。钩子的核心价值主动防御在错误发生之前进行拦截。这是它与事后靠人眼检查的本质区别。无感集成一旦配置好开发者无需额外记忆或操作安全策略自动生效。扩展性强理论上任何可以通过脚本判断的逻辑都可以做成钩子如检查代码中是否包含调试语句、是否引入了未经许可的依赖等。我配置的最关键的一个钩子是PreToolUse它在Claude每次试图执行Bash命令前都会先运行一个block-dangerous.sh脚本。这个脚本目前主要做两件事拦截对main分支的强制推送任何包含push --force main或push main --force模式的命令都会被立即终止。阻止提交.env文件任何试图将.env文件加入git暂存区的操作也会被阻止。#!/bin/bash INPUT$(cat) # 阻止强制推送到main分支 if echo $INPUT | grep -q push.*--force.*main\|push.*main.*--force; then echo 错误禁止强制推送至main分支。请考虑使用--force-with-lease或创建合并请求。 2 exit 2 fi # 阻止提交.env文件 if echo $INPUT | grep -q git add.*\.env\b; then echo 警告检测到试图添加.env文件。请确认该文件已加入.gitignore或使用环境变量。 2 exit 2 fi exit 0这个脚本的退出码2是关键它告诉Claude Code该命令被明确阻止。与之配套的settings.json配置如下{ hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: bash ~/.claude/hooks/block-dangerous.sh }] }] } }3. 系统架构与自动化搭建实战理解了三大组件后我们来看如何将它们组织成一个即开即用的系统。我的目录结构遵循“全局共享”与“项目独有”分离的原则最大程度实现复用。3.1 全局与项目目录结构详解~/.claude/ # 【全局目录】机器上所有项目共享一次性设置 ├── commands/ # 全局命令 │ ├── init-harness.md # 核心自动初始化项目缰绳 │ ├── new-project.md # 从想法到项目脚手架 │ └── session-resume.md # 会话恢复重载上下文 ├── hooks/ # 全局钩子脚本 │ └── block-dangerous.sh # 危险命令拦截器 └── settings.json # 钩子配置文件 your-project/ # 【项目目录】每个项目独立 ├── CLAUDE.md # 项目专属规则由init-harness生成草案 ├── progress.md # 当前任务进度追踪 ├── dev-log.md # 开发日志按功能记录 ├── docs/ # 设计文档、API说明等 ├── screenshots/ # UI截图、效果图存档 └── .claude/ # 项目级命令可覆盖全局 └── commands/ ├── workflow.md ├── plan-and-spec.md ├── tdd.md ├── ui-ux.md ├── verify.md └── commit.md设计思路全局区~/.claude存放放之四海而皆准的配置。比如拦截危险命令的钩子、创建新项目的模板流程这些逻辑在任何项目上都通用只需设置一次。项目区项目内/.claude存放与当前项目强相关的内容。比如针对本项目技术栈Next.js Supabase的workflow命令细节或者项目特定的代码生成规则。项目区命令可以覆盖全局区的同名命令实现定制化。3.2 一键初始化/init-harness 命令剖析这是整个系统的“点火开关”。无论是一个空文件夹还是一个已有项目你只需要输入/init-harness它就会在只读模式下分析项目然后自动生成全套配置。整个过程没有中间确认提示分析完直接生成非常流畅。步骤拆解步骤1项目分析只读零侵入这个阶段AI会像一位侦探一样扫描你的项目但绝不修改任何文件。它主要查看package.json确定技术栈如Next.js 15, TypeScript, Tailwind CSS。目录结构3层深度了解是App Router还是Pages Router是否有src目录模块划分方式。git log --oneline -20分析团队的提交习惯和规范是否使用feat/fix前缀。git branch -a了解分支策略是Git Flow还是简单的主干开发。.env.example推断集成了哪些外部服务如Supabase, Stripe, Resend。分析完成后它会输出一份简洁的报告并据此决定需要生成哪些命令文件。[项目分析报告] - 技术栈: Next.js 15 / TypeScript / Supabase / Tailwind CSS - 目录结构: App Router 无src/目录功能模块化组织 - 提交规范: 使用 feat/fix/refactor 前缀 - 分支策略: feature/* 分支直接合并至 main - 集成服务: Supabase (认证/数据库), Resend (邮件), Lemon Squeezy (支付) - 待生成命令: workflow, plan-and-spec, tdd, ui-ux, verify, commit步骤2生成 CLAUDE.md 草案基于分析结果AI不会套用一个空模板而是生成一个填充了具体内容的CLAUDE.md。例如它会自动加入“本项目使用Next.js 15的App Router所有组件应为React Server Components除非显式使用‘use client’。”“国际化所有用户可见文本必须使用next-intl从/messages/目录获取禁止硬编码字符串。”“绝对禁止强制推送至main分支提交.env或任何包含API_KEY、SECRET字样的文件。”步骤3 4生成命令与项目文件在项目的.claude/commands/目录下生成全套命令文件workflow.md,plan-and-spec.md等。同时在项目根目录创建progress.md任务进度、dev-log.md开发日志以及docs/和screenshots/文件夹。步骤5检查并补全全局文件最后检查~/.claude/下的全局命令和钩子是否存在如session-resume.md,block-dangerous.sh。如果不存在则创建它们如果已存在则保留原样。这确保了系统的完整性。实操心得init-harness生成的是优秀的起点但绝非终点。你必须手动审阅并完善它生成的CLAUDE.md加入那些只有你才知道的细节比如公司的内部库命名规范、特定的部署环境变量命名规则、代码审查的特定检查点等。把它当成一个帮你完成了80%工作的助手剩下的20%关键细节需要你亲自把关。4. 核心工作流从规划到交付的自动化流水线系统搭建好后日常的功能开发就变成了运行一条命令。以开发一个“用户反馈自动分类”功能为例你只需要输入/workflow “feedback auto-classify feature”。4.1 工作流引擎/workflow 命令全流程这条命令会触发一个完整的、自动化的流水线状态评估读取progress.md和最近的git日志理解项目当前所处阶段。分支创建自动创建并切换到新分支如feature/feedback-auto-classify。规划与设计调用/plan-and-spec命令。AI切换至“规划师”角色进行技术调研、可行性分析并输出详细的设计文档docs/spec-feedback-auto-classify.md。测试驱动开发调用/tdd命令。AI切换至“生成器”角色根据设计文档以“红-绿-重构”的循环进行编码实现。验证与验收调用/verify命令。AI切换至“评估者”角色将实际代码与设计文档逐项对比检查功能完整性、边界情况、i18n覆盖等并运行测试。提交与合并调用/commit命令。生成符合规范的提交信息推送分支并在设置允许的情况下合并回主分支。循环反馈如果第5步验证失败工作流会自动跳回第4步/tdd让“生成器”根据评估反馈进行修复然后再次验证直到通过。这个流程的强大之处在于角色的强制分离。让同一个AI在“规划”、“实现”、“验证”三个角色间切换相当于在团队中引入了“分权制衡”的机制能有效减少由于思维定势导致的盲点。4.2 角色扮演规划师、生成器与评估者的协同规划师 (/plan-and-spec)它的首要任务是“事实核查”。在写一行代码之前它会先问“这个想法真的可行吗”例如在实现“反馈聚类”功能时规划师会搜索确认pgvector扩展在项目使用的PostgreSQL版本中是否可用并核实其安装命令。调研Voyage AI或OpenAI的嵌入API确认其调用方式、费率、速率限制。查找类似的实现案例评估计算复杂度和性能。最终输出一份包含数据流图、API接口定义、数据库Schema变更和潜在风险的设计文档。生成器 (/tdd)它严格遵循设计文档进行实现。我特别在命令中加入了“模拟数据注入”的步骤每完成一个UI组件就要求AI生成并注入符合业务逻辑的模拟数据让界面立刻看起来是“活的”。这借鉴了之前手动截图验证UI的经验现在将其自动化了。如果实现过程中发现设计有误或可以优化生成器会立即更新docs/spec-*.md文件并说明变更原因确保设计与代码始终同步。评估者 (/verify)它的检查清单远不止“代码能否运行”。它会功能对比逐项核对设计文档中的需求点是否在代码中实现。完整性检查检查所有用户可见的字符串是否都已提取到国际化文件。错误处理验证API调用、用户输入等是否有适当的错误边界和用户提示。代码质量运行项目的lint和type check确保符合规范。构建检查尝试运行npm run build确保生产构建能通过。一次真实的成功拦截在开发上述聚类功能时生成器完成了核心的clustering.ts188行代码。评估者在验收时发现设计文档中要求的“余弦相似度阈值可配置”功能虽然相关UI控件已存在但后端处理逻辑中缺少了对该阈值参数的读取和应用。这个疏忽被成功捕获并在合并前得以修复。如果没有评估者这个独立角色这种“看似有实则无”的Bug很可能逃过审查直到上线后才被发现。5. 安全与效率的基石钩子配置与全自动模式5.1 安全钩子的深度配置前面提到的block-dangerous.sh是最基础的防线。在实际中你可以根据团队痛点无限扩展这个脚本。例如增加以下检查#!/bin/bash INPUT$(cat) # ... 原有的 force push 和 .env 检查 ... # 阻止安装来源不明的包例如从非官方源或特定黑名单 if echo $INPUT | grep -q npm install.*\\(example-malicious-package\\|--registryhttp://可疑源\\); then echo 安全警告检测到可能安装不安全的包。请从官方npm仓库安装。 2 exit 2 fi # 阻止删除特定重要目录或文件防误操作 if echo $INPUT | grep -Eq rm -rf.*\\(/src/app\\|/prisma/schema.prisma\\); then echo 危险操作试图删除关键目录或文件。请确认操作意图。 2 exit 2 fi # 阻止向生产环境数据库执行破坏性操作通过连接字符串判断 if echo $INPUT | grep -q psql.*DATABASE_URL.*prod.*\\(DROP\\|TRUNCATE\\); then echo 致命错误禁止对生产数据库执行DROP/TRUNCATE操作 2 exit 2 fi exit 0将这些检查集成到PreToolUse钩子中就等于为你的终端加上了一道“防火墙”。它不会影响正常的开发命令但会在你或AI即将执行高风险操作时紧急刹车。5.2 拥抱全自动模式--dangerously-skip-permissionsClaude Code有一个--dangerously-skip-permissions标志。启用后AI在执行需要确认的操作如运行安装命令、写入文件时将不再询问“是否继续”而是直接执行。很多人对这个标志望而生畏但关键在于危险的不是标志本身而是在没有安全措施的情况下使用它。我的工作流是先建立缰绳尤其是钩子再启用全自动模式。当block-dangerous.sh等钩子就位后全自动模式就成了效率的加速器。你可以放心地启动/workflow然后去喝杯咖啡回来时AI已经完成了从分支创建、编码、测试到提交合并的全过程。此时钩子扮演了“自动驾驶中的安全员”角色在关键时刻接管控制权防止系统驶入悬崖。5.3 上下文无缝恢复/session-resume开发中途Claude Code会话超时或中断是常事。传统的做法是你需要重新打开项目然后花时间向AI复述“我们刚才在做什么做到了哪一步接下来要干嘛。”有了/session-resume命令这个过程被极大简化。这个命令会读取progress.md的最后30行了解整体任务进度。读取dev-log.md的最后30行获取最近的开发细节。执行git log --oneline -10和git status掌握代码库的最新状态。综合以上信息生成一份清晰的摘要“我们正在开发‘反馈分类’功能。已完成聚类算法后端APIcommit abc123当前位于feature/feedback-auto-classify分支。下一步是根据docs/spec-*.md第3节实现前端管理界面。”这与你手动编写的CLAUDE.md维护规则形成了完美互补一个维护“静态规则”一个恢复“动态状态”。6. 常见问题与实战避坑指南Q1: 使用/init-harness后我就不需要自己写CLAUDE.md了吗A1大错特错。/init-harness生成的是一个优秀的、基于项目分析的草案。但它无法知道你们团队内部的特殊约定、特定库的怪异用法、或者部署环境的细微配置。你必须将其作为起点然后手动补充这些关键信息。正确的流程是运行命令 - 审查生成的文件 - 补充团队特有的规则和禁忌。Q2: 我必须每次都使用/workflow这种复杂的命令吗A2完全不必。这套系统的设计哲学是“该繁则繁该简则简”。对于修一个拼写错误、调整一个CSS样式这种小事你完全可以直接用自然语言告诉AI“把按钮的颜色从蓝色改成绿色。” 命令系统是为那些需要严谨流程的功能级开发准备的。钩子是始终运行的“后台守护进程”而命令是随取随用的“特种工具”。Q3: 这个结构能用于团队协作吗A3可以但需要调整。我目前的设置是为个人或小团队“直接合并到main”的快速迭代模式优化的。在严格的团队环境中你需要修改CLAUDE.md明确代码审查要求、PR模板、CI/CD触发条件。修改/commit命令将其从“直接合并”改为“创建Pull Request并等待审查”。可能需要在钩子中增加团队规范检查例如提交前必须通过所有CI检查。将全局配置~/.claude通过版本控制如一个内部模板仓库共享给所有团队成员确保一致性。Q4: 如何开始搭建自己的“缰绳”感觉无从下手。A4我建议采用迭代式搭建从最痛的点开始第一步立即行动创建你的~/.claude/hooks/block-dangerous.sh和settings.json。哪怕只实现拦截git push --force main这一条你也立即获得了一份巨大的安全感。第二步核心规则为你最常开发的项目类型如Next.js项目手动编写一个高质量的CLAUDE.md模板。这可能是投入回报比最高的部分。第三步自动化基于这个模板创建一个简化版的/init-harness命令让它能自动创建项目目录和基础文件。第四步优化流程当你发现某个开发步骤比如“写设计文档”总是被跳过或做不好时就为它创建一个专门的命令如/plan-and-spec把最佳实践固化进去。持续迭代每当你心想“要是AI能自动做X就好了”的时候就去看看能否通过新增或修改一个命令/钩子来实现它。最大的陷阱是试图一开始就设计一个完美、复杂的系统。这会导致你迟迟无法开始或者系统过于笨重而被弃用。记住“缰绳工程”的本质不是构建一个完美的框架而是将令你烦恼的事情一个一个地自动化掉。从一个钩子、一个命令开始让它先跑起来在使用的过程中你自然会知道下一步该优化哪里。
