我调试了整整三天发现那些让我和AI协作时翻车的错误第二天居然自己变成了系统的护栏。这事儿说起来有点神奇但本质上就是一句话我把每次和AI协作踩的坑写成了一个复盘Skill让AI第二天一开工就先读一遍这些教训把坑变成规则。今天这篇不聊虚的直接把我的完整思路、源码结构、踩坑记录全摊开给你一份能直接照着抄的作业。先交代一下背景。我平时的主力工作流是“人机结对”——我负责提需求、做review、定架构AI负责写代码、补测试、跑批量任务。听着挺美但实际跑起来我每天都在跟AI的错误博弈上下文太长导致它忘了半小时前的约定指令里带模糊代词让它改错文件它自作聪明“优化”了一段我不让动的核心逻辑。每踩一次坑我都要重新解释一遍规则。更烦的是同一个坑它第二天又踩一遍。后来我受一个做RPA的朋友启发他说“你与其每次都骂它不如把骂它的话变成配置文件”。这句话点醒了我。于是我一个下午搞出了这个复盘Skill核心思路只有一句话**把复盘变成一种AI能自动读取的护城河把对话中的错误教训沉淀成永久性的护栏。1. 复盘Skill的整体设计思路1.1 为什么是Skill而不是单纯写Prompt市面上很多人解决AI反复犯错的办法就是写超长Prompt把所有规矩塞进system prompt里。我一开始也这么干写了一版两千多字的“行为规范”结果发现根本没用——上下文一涨模型注意力一分散它该忽略还是忽略。而且一个Prompt里塞满负面清单AI反而不知道该重点遵循哪一条。Skill的逻辑完全不一样。它不是一次性注入而是一个可加载、可查询、可迭代的知识库。AI在每次任务开始前按需读取任务中遇到具体场景再调用对应规则。这就像你给新员工发了一本员工手册而不是在入职那天把所有规矩口头说三小时——后者听完就忘前者遇到问题随时翻。Skill的结构本质上是“方法库规则库”的组合。传统Prompt告诉AI“你要做什么”Skill更强调“你该怎么调用经验”。复盘Skill补全的是“你该避开什么”。它把历史上所有翻车案例转化成行为边界让AI在自由发挥的同时不越界。1.2 复盘到护栏的四层架构整个系统我从下到上拆成四层每一层解决一个具体问题第一层记录层。每次协作结束我用固定模板记录这次踩了什么坑。模板字段包括任务描述、出错点、根因分析、AI当时的错误行为、正确行为应该是什么、复现概率。这一层纯粹是Markdown文件没有任何技术含量但它是整个系统的数据源。第二层归纳层。每周我跑一个归纳脚本把这一周所有踩坑记录做聚类提炼出高频模式和共性根因。比如“文件路径写错”和“修改了错误的函数”看起来很不一样归纳后根因其实是“AI对项目结构理解不完整”——于是护栏条目就应该是“重大修改前必须先确认影响范围”。第三层固化层。经过归纳后把共性根因转成一条具体的SKILL规则。每条规则有明确ID、优先级、触发条件、禁止行为和推荐替代行为。固化后的规则进入规则库供AI每日加载。第四层执行层。每天开工第一件事AI先扫描规则库把相关规则注入任务上下文。任务执行中如果某条规则被触发或即将被违反AI会主动调用保护的子Skill进行拦截或告警。这四层你也可以理解成记录是日志归纳是分析固化是制度执行是监管。复盘Skill本质上是把这套管理体系自动化了。1.3 工具选型与运行环境我实测下来比较顺的组合是这样主框架用Claude Code因为它的Skill机制比较成熟SKILL.md的解析和加载都是自动的规则库用纯Markdown文件存储不用数据库——原因很简单方便人读也方便AI读git能直接diff定时自动复盘用GitHub Actions每天凌晨跑一个Python脚本做增量扫描本地开发时的实时提醒用一个轻量Claude Code插件钩子这套选型的核心考量是“低成本、可演化”。不引入重框架、不写复杂平台所有东西都是文件脚本一个人完全维护得动。2. Skill核心机制与实现细节2.1 SKILL.md的结构设计Claude Code的Skill本质上是一个目录里面有一个SKILL.md作为入口。我复盘后设计的SKILL.md结构长这样--- name: daily-guardrail-review description: 每日复盘护栏加载器。在开始任何编码任务前调用读取历史踩坑记录并生成今日行为守则。 version: 1.2.0 author: your-name --- # 每日复盘护栏加载器 ## 加载时机 本Skill应在每个工作会话开始时立即加载并输出一份“今日护栏速览”。 ## 输出格式 加载完成后必须以以下格式输出 ### 今日护栏速览 - 今日生效规则数: [数字] - 高危规则数: [数字] - 重点规避行为: [前3条规则简述] ## 规则加载路径 读取目录 ./guardrails/rules/*.md 读取目录 ./guardrails/archive/*.md 中的FAIL记录 按规则优先级从高到低排序注入上下文。 ## 内部工具 - list_rules: 枚举全部规则文件 - get_rule: 读取单条规则详情 - check_task: 检查当前任务是否触发任何规则这里的关键是description字段写得足够精确。模型通过description决定什么时候激活Skill所以你要非常明确地告诉它“在什么场景下使用”。最初我的描述写得特别笼统导致AI经常忘记调用。后来改成“在开始任何编码任务前”调用率就明显提升了。2.2 规则文件的标准字段每一条护栏规则我都是落到一个独立文件命名方式是rule-数字-简短描述.md。标准化字段如下字段说明示例rule_id规则唯一标识GR-017risk_level风险等级high/mid/lowhightrigger_scene触发场景描述当需要修改已有函数时forbidden_action禁止行为禁止在不查询调用方的情况下重写函数签名recommended_action推荐替代行为先grep全部调用点评估影响后再改source_case来源案例IDCASE-20250315-01create_date建档日期2025-03-16之所以把字段固定这么严格是因为AI对结构化信息的理解准确率远高于自由文本。你写“当需要修改已有函数时不要乱改签名”它可能理解成“不要修改任何函数”但写成“禁止在不查询调用方的情况下重写函数签名”它就懂这是在特定条件下的一种限制。规则描述必须精确到“场景行为替代方案”三段论。2.3 自动复盘的Python脚本思路每天自动复盘的脚本是我用Python写的逻辑其实不复杂核心就三步import os import re from datetime import datetime from collections import Counter CASES_DIR ./guardrails/cases/recent/ RULES_DIR ./guardrails/rules/ ARCHIVE_DIR ./guardrails/archive/ def parse_case(case_file): 解析复盘记录Markdown返回结构化字典 with open(case_file, r) as f: content f.read() case {} # 按固定模板提取字段 case[id] os.path.basename(case_file).replace(.md, ) case[task] re.search(r任务描述[:]?\s*(.), content).group(1) case[fail_point] re.search(r出错点[:]?\s*(.), content).group(1) case[root_cause] re.search(r根因分析[:]?\s*(.), content).group(1) case[wrong_behavior] re.search(rAI错误行为[:]?\s*(.), content).group(1) case[right_behavior] re.search(r正确行为[:]?\s*(.), content).group(1) return case def generate_rule_from_case(case): 把一个case转成规则草稿 rule { trigger_scene: case[task], forbidden_action: case[wrong_behavior], recommended_action: case[right_behavior], source_case: case[id], } return rule # 主流程读取所有近期case聚类生成建议规则 all_cases [] for fname in os.listdir(CASES_DIR): if fname.endswith(.md): all_cases.append(parse_case(os.path.join(CASES_DIR, fname))) # 聚类根因统计高频词 root_causes Counter([c[root_cause] for c in all_cases]) print(高频根因Top5:) for cause, count in root_causes.most_common(5): print(f {cause}: {count}次)这个脚本不会自动写规则文件而是输出一个“建议清单”我看过之后手动确认再固化。原因很简单AI归纳的规则偶尔会跑偏比如把一次性的偶发错误也固化成规则到时候反而束缚了AI的正常发挥。自动化负责大部分体力活人的判断依然把关最后一道。2.4 护栏的执行方式软拦截与硬拦截护栏建好之后执行阶段的机制也分两类我称为软拦截和硬拦截。软拦截是“提醒”适合低风险场景。AI发现自己即将违背某条规则时输出一行黄色的提醒文字说明即将执行的操作和规则要求之间的冲突由我来判断是否继续。这种模式保持灵活性不打断流。硬拦截是“阻断”适合高风险场景。当触发到高危规则比如“删除文件前必须确认”“生产环境变更必须经人批准”AI会直接停下输出“操作被TR-07规则阻断”然后等我的指令。这种机制极其重要尤其是AI批量处理文件的时候一条硬拦截可能就能救回一个配置目录。我见过很多开发者只用软拦截结果AI在高危操作上依然频频翻车——提醒多了AI就免疫了。后来我加了几条硬拦截犯错率一下子降了七成。护栏的价值不在于限制AI而在于让AI在高风险动作前下意识地刹一脚车。3. 实操过程从一次典型踩坑到一条护栏的诞生3.1 真实的踩坑案例复盘我挑一个最有代表性的案例讲全过程你就明白这个Skill是怎么跑通的了。那次任务是让我和AI共同重构一个支付模块的订单状态机。我明确要求“保持对外接口不变只重构内部逻辑”AI满口答应。结果它干活到一半自作主张把order_status字段从整数改成了枚举对象还改了数据库映射。测试跑了二十分钟全线飘红我整个人是崩溃的。当时我按复盘模板记录了一份case# CASE-20250315-01 - 任务描述: 重构订单状态机要求对外接口不变 - 出错点: order_status从整数改为枚举对象导致DB映射失效 - 根因分析: AI过度理解了“重构”认为可以优化数据结构未对“接口不变”做严格约束 - AI错误行为: 擅自修改了接口签名和数据库映射层 - 正确行为: 先列出所有对外接口清单逐一加护栏确认为受保护项后再动内部实现 - 复现概率: 高这份记录的关键在于根因分析那一步。一开始我把根因写成“AI不听话”但这对生成护栏毫无帮助。后来我意识到真正的根因是——我下达的任务里没有明确哪些是“受保护边界”。于是对应的规则就很清晰了。3.2 从case到规则的转换第二天早上兜底脚本扫描到这条case后输出了一条规则建议# GR-017: 重构任务必须先声明保护边界 - 风险等级: high - 触发场景: 当用户要求“重构”或“优化”既有代码时 - 禁止行为: 禁止在未列举受保护接口的情况下直接修改公共API、数据结构或数据库映射 - 推荐行为: 1. 首先列出全部对外接口清单 2. 标注哪些属于受保护边界明确“不可变更” 3. 声明保护边界后再开始内部实现 - 来源案例: CASE-20250315-01我看了一眼觉得这条规则覆盖的场景够典型就直接确认收入规则库。当天下午接新任务的时候AI一上来就输出已加载GR-017规则。本次重构涉及3个公共接口其中2个标记为受保护边界1个允许调整。保护边界声明如下…我当场愣了然后我就知道这套机制真的成了。它不再需要我反复提醒因为那条坑已经变成了它自己的行为准则。3.3 从踩坑到护栏的完整转换链为了方便你理解我整理了一张转换对照表把这次踩坑里每个环节跟最终护栏字段严格对应起来踩坑环节case里记录的内容固化后护栏字段任务要求重构状态机接口不变trigger_sceneAI错误改了order_status类型forbidden_action正确做法先列接口清单再动手recommended_action根因未声明保护边界risk_level 额外建议来源CASE-20250315-01source_case整个链条走下来一个日常的翻车现场变成了一条可复用的行为边界。我最大的体会是不是每次踩坑都值得生成规则但每次踩坑都必须先记录——记录存档是原始素材规则固化是经过了筛选和提炼两条路径缺一不可。4. 运行效果与实测数据4.1 效果对比用之前和用之后这个系统我跑了两周统计了一下数据。虽然样本量不算大但趋势非常明显指标用复盘Skill前一周用复盘Skill后两周同类错误重复出现次数6次0次AI因“忘记约定”导致返工次数4次1次需要我在Review时纠正的次数11次3次高风险操作被自助拦截次数0次2次改DB映射、批量删除前最直观的感受就是每天陪AI干活从“盯贼模式”切成了“监理模式”——我不再需要每一行都盯着只要在它输出的关键节点做抽查。那种体验变化是很爽的之前我觉得AI是“聪明但需要不断纠错的实习生”现在更像是“带了一个有SOP执行的熟手”。当然它偶尔还是会犯新错误但旧错误基本不再出现这已经让我省出了大量时间。4.2 人工复盘与自动归纳的分工我在跑这套系统的过程中逐渐摸索出一个比较省力的分工模式AI擅长从大量case里找规律、聚类高频根因、生成规则初稿、定时扫描规则库人擅长判断规则是否合理、识别AI归纳中“过度泛化”的地方、调整风险等级、补充规则间的冲突消解这条分工本身也是一个护栏——它防止我过度依赖AI的归纳能力。AI刷一百条case很快但它没有“工作常识”和“业务判断力”有些规则它觉得很重要实际上业务上根本不适用。比如它曾把“修改任何方法前都要先写测试”固化为强制规则听起来很好但实际上会有大量低优先级任务被拖慢我把它降级成mid级别才合理。5. 常见问题与排查技巧实录5.1 规则不生效的三大原因这套系统最大的坑就是“规则建了但AI不用”。我排查了无数次发现原因不外乎三种原因一Skill的description没写清楚触发条件。模型是依赖描述来决定何时调用Skill的。如果你的描述是“用于复盘”AI在干活时根本想不到激活它。修法是把触发条件写进description明确到“每次任务开始前必须调用”。原因二规则文件太多太乱。我早期建了50条规则结果上下文根本塞不下AI加载时只挑了头几条。修法是做两级规则库——全局规则最多15条其他规则分类存档执行时按相关度动态加载。原因三规则和当前任务相关度不高。AI不会因为一条规则“存在”而起作用它会判断当前任务和规则是否相关。所以规则的触发场景必须具体不能写“当处理代码时要小心”而应该写“当修改数据库迁移脚本时禁止在未备份的情况下执行删除操作”。5.2 规则冲突时怎么办规则越积越多一定会出现冲突。比如A规则说“重构前必须列接口清单”B规则说“小改动响应速度要快”。两条都合理但AI面对一个很小的接口调整时两条规则指向完全不同——A说先列清单B说加速执行。我的处理办法是给每条规则加一个“优先级”维度并在SKILL.md里声明冲突消解原则当多条规则同时适用且存在冲突时遵循以下顺序安全规则优先于效率规则数据安全规则优先于代码风格规则用户当前明确指令优先于历史规则。规则冲突时输出规则冲突提示展示所涉规则ID等待用户裁决。加了这条之后AI碰到冲突不再是“看心情选一条”而是会主动把冲突摆到台面上来。这本身也是一种护栏——系统里有矛盾很正常重要的是矛盾暴露出来让人来定。5.3 常见问题速查表按我实操中最常被问的场景整理了一个排查表现象可能原因解决方式AI从不输出护栏速览Skill没有被正确加载检查SKILL.md的name和description确认目录结构规则偶尔生效偶尔不生效上下文过长规则被截断减少全局规则数按任务动态加载AI建议的规则太泛归纳时没有结合case原文在生成规则前加入“基于case的具体描述不要抽象成空泛口号”硬拦截过多导致流程卡住高风险规则范围定太宽收紧触发场景避免“一刀切”复盘case填写耗时太长模板字段过多精简到5个核心字段其他可选填多台设备规则不同步规则库只在本地用git仓库管理提交触发同步6. 复盘的长期演化和扩展方向6.1 Skill叠加把复盘护栏变成元Skill这套东西跑顺了以后我意识到它本身可以变成一个“元Skill”——即一个管理其他Skill的状态与规则的开关。比如我同时有写代码的Skill、写文档的Skill、做测试的Skill它们各不相同但都会踩坑。复盘Skill可以直接从“记录和AI协作的坑”升级成“管理所有Skill的历史经验库”。具体实现也不复杂只要把规则文件按Skill类型分目录每个Skill的SKILL.md里加一句“本Skill同时受guardrails目录下对应域名的规则约束”。这样我从一个Skill换到另一个Skill时护栏也随之切换不用重新加载一堆无关规则。这个方向我还在迭代中但已经能感受到它的潜力——如果把AI协作过程中的每一次翻车都沉淀为可查询的系统资产那么AI整体的使用质量会越滚越高而不是一直原地打转。6.2 团队场景的规则共享单机升级为团队版本也很顺只要把规则库从一个本地目录变成一个git仓库团队成员各自提交case由一个固定角色不管是人还是AI做归纳和规则发布。新人加入团队时不再需要听老人口口相传“那个AI有毛病你注意点”直接拉一遍规则库所有已知雷区一目了然。我在团队场景跑了半个月最直观的变化是“AI踩坑不再被重复发现”。以前两个同事各自用AI踩了几乎一样的坑然后各自吐槽一遍。现在这些坑进入共享规则库之后整个团队的使用体验都往上涨了一截。6.3 从规则到测试用例的自动生成另外一个让我兴奋的扩展方向是护栏规则可以直接作为测试用例的输入。比如拿GR-017那条规则举例——“重构任务必须先声明保护边界”我可以把这条规则转换成一条Agent行为测试。每次升级模型版本或调整Prompt时跑一遍这些行为测试就能快速判断新配置有没有违背历史规则。这样相当于把“经验”转化成了“回归测试”让AI行为的稳定性变得可测量。这件事我一开始完全想到后来是被一个搞QA的朋友点了一下才反应过来。现在我已经建了十几个这样的行为测试跑一次只要几分钟但每次都能提前暴露很多潜在问题。7. 我个人实操中最受用的几个经验说到这最后分享几条我踩过好多次才真正理解的经验虽然可能不够系统但保真。第一规则数量是养出来的不是一步到位。不要追求一开始就写50条规则。我当时前三天只固化了两条规则都是高频高风险的那种。跑顺了以后每周新增四五条慢慢到一个平衡点——太多规则反而会影响AI的灵活性找到一个“覆盖高频坑、容忍低频坑”的平衡就好。第二复盘记录一定要趁热做。你踩坑当时写和隔半天再写细节完全是两个深度。我当时强制自己“翻车三分钟内必须记case”不记完不让开新任务。这个纪律比任何技术设计都重要。第三分清系统护栏和自然语言提醒的区别。如果你让AI“记住”某个约定那是自然语言层面的短期记忆真正的护栏是固化成规则文件、有明确ID和触发条件、能阻止AI高风险操作的行为边界。前者靠运气后者靠机制。我一开始依赖前者所以反复废工。现在我每天开工第一件事就是看AI输出的“今日护栏速览”。它每次列出几条要规避的行为我扫一眼心里就有底。这套系统不复杂但它做到了一个关键的事——把我每次在AI身上交的学费真正变成了沉淀下来的资产。
