你有没有这种感觉——同一个AI编程助手在别人手里像干了十年的老兵到了你手里连你上礼拜刚拆分的模块都记不住。每次它都很客气地说“你好有什么可以帮你”然后你只能再花十分钟去解释我们的项目分层是这样的我们用 Java 17 加 Spring Boot错误处理必须走错误码……第一天你还有耐心第十天你已经开始怀疑人生了。这大概是每个重度使用AI编程助手的人都会撞上的墙模型能力很强但记忆窗口很短。它不是智商不够是你从来就没给它准备过一本“操作手册”。我最近折腾的一套小方案就是为了解决这个事。思路不玄乎把项目的各种约定、经验、偏好写进几个叫 steering files 的文件里再配一组叫 kiro hooks 的自动钩子在合适的时机把对应的内容精准地喂给AI助手。做到后面你会发现它不是越用越懂你而是你越来越会教它——结果就是它写出来的东西越来越像你们团队自己人写的。这个方案不依赖任何特定的IDE或者云平台纯本地文件加几个脚本人人都能照着搭。下面我把文件格式、钩子触发、迭代方法、踩过的坑全部交代清楚。1. 先别急着写代码先确认痛点在哪儿1.1 我实际遇到的三种“AI失忆”现场我实际见过比较典型的三种失忆现场。第一种是架构失忆。项目做到中期模块拆分、依赖方向都已经有明确约束。你让AI助手在某个模块里加一个功能它可能会顺着当前文件乱引用甚至跨层调用因为没有文件告诉它“你只能依赖service层的接口”。它对项目架构的了解完全建立在当前打开的十几个文件上只要其中一个文件里有个旧写法它就会照着旧写法扩散。第二种是约定失忆。你们团队的错误处理方式、命名规范、commit信息格式都在代码评审里反复强调过但AI助手每次都是第一次听说。我见过有人为了统一风格往每个新文件开头都贴一段注释最后代码里全是噪音维护成本直线上升。第三种是踩坑失忆。某个接口的用法定死了换一种写法在特定版本下有bug某个配置项不能改改了线上会出问题。这些经验你不可能每次都写进prompt里但不写它就还会踩同样的坑。这三种情况往深了说本质是一件事AI助手的每次对话都是冷启动它对你的项目没有长时记忆。市面上的AI编程产品普遍提供了类似自定义指令、规则文件之类的功能但在一个复杂项目里固定文本根本不够用而且更新成本很高。所以我开始想能不能把它做成一套项目内可积累、可自动化加载的记忆系统。1.2 换个思路把上下文工程变成项目基建关键转变在于不要指望AI记住你而是把“你希望它知道的东西”沉淀成文件再设计一套自动注入机制。这其实是把软件开发里的一个老思路搬到了AI交互领域——把易变的知识从代码里拿出来放到配置文件里让程序在运行时加载。这里的“程序”就是AI助手工作流“配置文件”就是steering files。这个思路有个额外的好处文件和Git天然亲和。谁改了什么、哪条经验是哪次事故沉淀下来的都有历史记录可以回滚、可以评审。它不像对话历史那样是个黑盒而是一等公民可以review可以测试可以随着项目一起演进。于是就有了这套方案的架构雏形。2. kiro hooks 和 steering files两个关键概念拆解2.1 steering files给AI看的“项目操作手册”我习惯把steering files比喻成新员工入职手册。它不负责教AI怎么编程那是它本来就懂的而是告诉它这个项目的世界长什么样我们怎么做事遇到过什么坑。在实际项目里我推荐按下面的结构存放这三份文件.kiro/steering/base.md个人或团队通用的编码偏好。比如注释语言、命名风格、commit粒度、禁止使用的反模式。这部分可以跨项目复用。.kiro/steering/project.md当前项目的架构地图。比如目录职责、模块边界、技术栈版本、核心数据流、部署环境等。是给AI的第一份地图。.kiro/steering/history.md经验日志。按时间追加每条记录包含“场景-现象-原因-结论”。遇到类似问题AI可以在这里搜到旧方案。这个文件系统可以直接拿一个pull request来维护。每次有新知识就提交一次变更每次发现文件里有过期内容就开issue修掉。我给文件里每条规则定了一个标准格式方便AI解析也方便人写字段说明例子范围这条规则作用于哪个模块/场景支付模块规则期望的行为或约束严禁直接操作数据库表必须走仓储接口理由为什么要有这条规则表结构可能重构避免散落的SQL反例它阻止了什么错误做法不推荐写原生SQL加上“理由”这一栏是我觉得很重要的点。AI很擅长模式匹配但如果你只告诉它“不能这样”它容易在别的场景继续犯类似的错误如果告诉它为什么它就能迁移到相似问题上这个在实践里效果非常明显。2.2 hooks在正确的时间递上手册文件放在那儿AI不会主动去看。你需要一个机制在“该知道的时候”把“该知道的内容”送进模型上下文。这就是hooks的职责。我实现了一套很轻量的钩子机制核心触发点有这些session_start新建对话时注入base.md和project.md。file_open打开某个源文件时注入该模块的职责说明和历史风险。触发频率高所以内容要精简。pre_generate准备生成代码前注入目标文件涉及的相关接口、风格约束。post_edit每次AI改完文件自动追加一条变更摘要到history.md里。这一步是整个方案能越用越聪明的关键。task_done一次任务完成后提取本次对话里产生的关键决策人工确认后写入steering files。你没看错这个方案不是单向地喂给AI知识更关键的是让AI在使用过程中不断把新经验写回文件。这就形成一个循环读文件→应用到任务→记录新经验→下次读文件时包含这些经验。循环跑起来它就一直在长。2.3 两者结合后的整体工作流我来描述一下这套闭环的实际运行方式你启动一个AI辅助任务shell wrapper先检查有没有.kiro目录有就按顺序读入steering files的核心区块拼进系统提示词任务进行中每当AI写入文件watcher会捕获变更事件自动生成一条结构化的提交记录等到任务结束你再花半分钟review一下history里的新增条目把有价值的经验提炼进project.md或base.md。换句话说hooks是“输入与输出的调度器”steering files是“记忆的存储层”。没有hooks的文件是死文档没有文件的hooks是空转的定时器。两者配合才能形成一套有生命的项目知识体系。3. 手把手搭一套可复用的引导体系3.1 目录结构与初始化脚本先假设你手上有一个真实项目路径是~/work/demo-service。第一步是在项目根目录建一个.kiro目录。我直接贴一下初始化时的目录结构.kiro/ ├── steering/ │ ├── base.md │ ├── project.md │ └── history.md ├── hooks/ │ ├── pre_task.sh │ ├── post_edit.sh │ ├── session_start.sh │ └── task_done.sh └── bin/ └── kiro不需要任何第三方依赖纯shell和Python就能跑起来。如果你们团队有统一的脚手架也可以直接把.kiro模板放进脚手架里新项目自动带出来。初始化脚本做的事情很简单生成目录、创建三份空的steering文件、填充文件用途注释头。我一般在project.md里预填当前判定得到的技术栈和目录结构这些信息越早给AI越能避免它在一开始就放飞自我。3.2 第一版引导文件怎么写三个文件的样例别想着一次写完美。第一版只做一件事把项目里那些只要问一个老员工就立刻能答上来的信息写进去。我拿一个模拟项目举例。base.md的第一版大概长这样# 通用编码偏好 ## 语言与注释 - 代码注释使用中文但公共API的docstring使用英文 - 禁止在注释里写“这段代码是做什么的”这废话要写“为什么这样做” ## 命名 - 函数/变量名使用camelCase类型使用PascalCase - 数据库表名使用snake_case且必须带模块前缀 ## 命令 - 所有CLI工具必须提供--help - 脚本失败时返回非零退出码并在stderr打印原因project.md的重点是“地图”# 项目模拟订单服务 ## 技术栈 - 语言: Go 1.22 - 存储: Postgres 15 Redis 7 - 队列: RabbitMQ 3.12 ## 架构 - 四层分层handler → service → repository → storage - 禁止跨层调用handler不能直接碰storage - 模块间通信走内部事件禁止直接实例化其他模块 ## 风险区域 - 支付回调接口必须做幂等处理参考standby/idempotent.go - 库存扣减使用乐观锁禁止先查后扣history.md一开始是空的我先写一条示例# 经验日志 ## 2024-11-02 库存超卖问题 - 场景: 并发下单时库存扣减出现负数 - 原因: 使用先查后改而非原子条件更新 - 结论: 库存扣减必须用 UPDATE ... WHERE stock ? 的方式这三份文件加起来不超过60行。你会发现它内容很少但AI拿到它以后生成的代码立刻就不会再犯那些基础架构错误了。很多时候不用贪多几条精准规则胜过一大段泛泛而谈。3.3 钩子实现一个几十行的调度脚本我实际用的hook引擎非常简单逻辑都写在一个Python脚本里。核心代码大概长这样#!/usr/bin/env python3 import sys, subprocess from pathlib import Path ROOT Path(__file__).resolve().parent.parent HOOK_DIR ROOT / hooks def run_trigger(trigger: str) - None: file HOOK_DIR / f{trigger}.sh if file.is_file(): print(f[kiro] run {file.name}) subprocess.run([bash, str(file)], checkFalse) if __name__ __main__: run_trigger(sys.argv[1])调用方式就是.kiro/bin/kiro pre_task每个钩子脚本只负责一件事。例如pre_task.sh负责把steering files里任意任务都需要的信息拼起来#!/usr/bin/env bash STEERING_DIR$(dirname $0)/../steering cat EOF PROJECT CONTEXT $(cat $STEERING_DIR/project.md) CODING STYLE $(cat $STEERING_DIR/base.md) END CONTEXT EOF你甚至不需要写代码直接把这些脚本的输出复制粘贴到AI助手的对话里也行。我最初就是这么干的复制了几次以后才决定做成自动注入。post_edit.sh我用来捕获变更摘要原理是先用git diff统计变更再把摘要追加到history.md#!/usr/bin/env bash CHANGE_LOG.kiro/steering/history.md { echo echo ## $(date %Y-%m-%d) 变更摘要 echo - 文件: $(git diff --name-only | tr \n ) echo - 说明: 待人工补充 } $CHANGE_LOG这只是一个原型脚本。实际生产环境里我还会加上文件分类和去重逻辑避免AI每改一个文件就堆一条完全没信息量的日志。人工确认的好处也在于此避免把AI的胡言乱语也沉淀成经验。这套机制里永远是人来做最终裁判AI只负责草拟。3.4 接入日常工作的三种姿势第一种把钩子接到命令行工具里。比如你有一个内部CLI原本跑测试是task run test现在把它包装成先执行kiro pre_task再执行原命令AI拿到的上下文就是最新的。第二种直接粘贴。不想动工具链就在开始一次复杂对话前手动跑一下.kiro/bin/kiro pre_task把输出的上下文粘贴进对话。虽然笨但对没有CLI的纯IDE用户来说最省事。第三种用编辑器插件或任务宏。如果你的编辑器支持任务或宏可以在打开项目事件里自动执行session_start脚本。现在主流IDE基本都支持配置一次能用很久。3.5 快速验证闭环是否跑通搭好以后我建议用三个测试用例验证一下。问AI“这个项目用什么语言和数据库”看它是否能直接从project.md里回答而不是猜。故意写一段跨层调用代码看它会不会警告你不符合架构。在history.md里加一条新踩坑记录然后在一个新对话里问“我要做类似的事情有什么要小心”看它是否引用那条记录。如果三个都能通过说明这套体系从读取到注入到回写的闭环已经建立起来了。4. 怎么能让它越用越聪明反馈循环的三个关键细节4.1 经验沉淀的流程AI草拟人确认文件固化我要强调一个原则不要直接让AI往steering files里写历史经验。我见过有人把post_edit做成全自动结果三天后文件里躺着一堆互相矛盾的结论AI照着做反而出错。全自动写入的问题在于AI自己也是概率模型它对自己刚产出的代码判断不一定可靠有时候会把临时方案误记成长期约定。我推荐的流程是AI先写到一个inbox.md你每天花两三分钟把它归并进正式的history.md。归并时做两个筛选这条经验是否已被旧条目覆盖它是否只适用于一个临时场景两个条件都满足才能进正式文件。这个人工闸门是保证文件可信度的基础。4.2 定期“知识压缩”从日志变成规则随着项目推进history.md会越来越长。这时候如果不整理AI的上下文窗口会被大量历史细节占满反而降低精度。我一般每两周做一次压缩把已经稳定执行的结论从history.md提升到project.md或base.md的正式规则里把被反例验证过的旧方案从history里标成“已废弃”把重复出现的相似记录合并成一条这个过程很像代码重构。压缩之后steering files保持精简但每一条都更有分量。半小时的整理能省下后面几周反复解释的时间。4.3 跨项目复用把base.md做成团队资产base.md里的内容是通用的比如命名风格、注释规范、commit规范值得沉淀成团队资产。我们团队用了一个简单办法把base.md模板放在一个公共仓库里新项目初始化时自动拷一份遇到全团队共识的变化改模板而不是挨个项目改。project.md则是完全个性化的复制意义不大。history.md如果要跨项目复用通常是高度抽象后的结论比如“缓存失效要用版本号而不是时间戳”这种可以转移到base.md里。4.4 多人协作时的注意事项steering files放进Git以后就会面临合并冲突。不过因为它是文本文件冲突解决起来很容易。更重要的是约定review规则任何修改steering files的PR必须附上说明项目管理员合并前确认这条修改不会让文件长度膨胀使用git blame查看某条规则的来源回滚错误决策很方便多人同时维护时最容易出现的是规则互相覆盖。我们现在的做法是每条规则都带一个owner字段谁提的规则谁负责后续维护。遇到意见不合拿历史记录说话而不是拍脑袋。5. 踩过的坑和排查方法5.1 上下文爆炸注入太多导致AI丢了西瓜一开始我贪心把history.md全文都塞进每一次对话。结果AI遇到具体问题的时候反而被大量无关历史带偏回答质量明显下降。后来改成“分场景注入”base和project进首批上下文history只按关键词触发比如用户提到“库存”“超卖”“幂等”才追加对应的经验区块。关键参数是单次注入总字符数控制在3000字以内优先保证最前面三分之一是最高优先级规则。5.2 引导文件“老化”规则和现状脱节项目重构后我忘了同步project.mdAI还拿着旧的架构说事。从那以后我定了规矩任何模块迁移、依赖升级PR里必须包含steering文件的同步更新review时单独检查。工具方面我会定期跑一个diff比对project.md里描述的目录结构和实际仓库不一致就报警。5.3 钩子静默失败经验断流但没人发现post_edit写文件失败时脚本没提示日志在哪都没找着结果一个星期history都没更新。后来我给每个钩子加了日志和失败标记每次任务结束输出一行“本轮已归档3条变更”没输出就说明挂了。自动化越安静越容易无声地坏掉必须能看见心跳。5.4 安全和隐私别把密钥写进引导文件你会在steering files里写很多项目细节如果这个仓库不小心公开等于把架构弱点拱手送人。我建议把steering files加入.gitignore尤其是history.md里可能包含安全事故细节或者提供一个脱敏版本。还要提醒不要把正在用的API key、数据库地址直接写进去真要记录写成占位符加查找路径。5.5 常见问题速查表症状可能原因处理办法AI完全不理会引导文件hooks没生效/注入顺序不对检查pre_task输出是否在对话开头AI老是提新方案但不符合架构project.md里架构规则太弱增加“禁止跨层调用”类的强约束history导致回答跑偏历史注入过多且无触发条件改为按关键词触发多人改完文件冲突严重缺少owner机制每条规则标注ownerPR时提前同步新成员不知道有这套东西缺少onboarding入口在README和PR模板里加说明最后分享一点真实体会。这套方案本身不复杂难的是坚持维护。我见过很多团队把steering files建好以后就没再动过几周后就和项目脱节了等于白搭。要让这套机制真正跑起来关键是把它嵌进日常工作流而不是当成额外负担。让AI草拟、你只做快速确认让文件随PR同步更新规则和真实代码保持同频。久而久之你会发现AI的建议越来越像团队里资深成员给的review意见——倒不是说它突然变聪明了是因为你们把团队的项目知识变成了一条持续的输入流。如果你也受够了每天重复教AI项目背景不妨从今天开始给你的项目建一个.kiro目录从三份文件开始。