文章目录前言1 先聊聊咱们都踩过的那个坑1.1 AI写代码快是快就是记不住自家规矩1.2 最省事的办法后来都成了麻烦2 我琢磨着这事儿不能硬堆文本2.1 先定了三个不能让步的目标3 分层结构说白了就是分级投喂3.1 四层分别管啥4 路由入口为啥要单独整个manifest文件4.1 这里面装了三种关系4.2 关键词为啥要拆成小分片5 匹配上了可不敢直接就干活5.1 我们拆成了四步走6 主题文件为啥只写精简事实6.1 短了才好组合7 知识写完了咋存回去才不打架7.1 直接改文件多人协作必炸7.2 我们整了个结构化变更文件7.3 用版本号拦住过期修改8 个人任务和团队知识为啥要分开8.1 放一起必乱9 实际跑了一圈啥感受10 这方案也不是万能的11 最后唠两句P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/qq_34419312前言现在做开发的谁还不用AI写两行代码说个很扎心的现状AI编码速度越来越离谱一天能产出过去一周的代码量。可项目维护难度呢涨得比代码量还快。你说离谱不离谱。1 先聊聊咱们都踩过的那个坑1.1 AI写代码快是快就是记不住自家规矩比如你让它写个退款接口咔咔两下就写完了。转头就问你咱们这个接口支持重试不幂等键用啥字段啊这个状态是谁来维护啊你说气人不气人这些东西代码里、文档里明明都有换个会话它就全忘光了。每次都得重新扒仓库找答案找着找着半天就过去了。合着AI省下来的时间全给它擦屁股用了。1.2 最省事的办法后来都成了麻烦一开始大家想的招都很直接把所有规则全写AGENTS.md里呗。项目小的时候确实好使几十行字Agent一眼看完。等项目做个一年半载你再看那文件膨胀得跟气球似的。Agent每次会话先加载几千字废话真正有用的规则没几条还容易被淹没在里面。上下文烧得快效果还拉胯纯纯赔本买卖。2 我琢磨着这事儿不能硬堆文本我们做Flow2Spec的时候就换了个思路项目知识不是堆得越多越好得能按需找、能串起来、能查缺补漏代码改了还能跟着更新。说白了就是别让AI瞎读该读啥读啥。2.1 先定了三个不能让步的目标第一个不能为了个小需求就让AI把整个项目文档全读一遍。成本太高了就像你只想买瓶水没必要把整个超市逛一遍。第二个命中一条规则不算完相关的依赖也得自动补上。比如讲支付规则你不能不提账户风控、订单边界不然说的全是半截话。第三个这些知识得能进Git、能走Code Review。不能搞成个黑盒子谁改了啥、为啥改全查不着。3 分层结构说白了就是分级投喂最后我们整了个四层的知识结构一层比一层深。不是啥花活核心逻辑就是简单问题浅层解决实在不懂再往深了挖。3.1 四层分别管啥L0就是个路由索引纯机读的相当于个目录。AI进来先看这个快速缩小范围不用瞎蒙。L1是关键词分片存触发词相当于书的索引页。哪个任务对应哪些关键词对上了再打开对应的文件。L2是主题摘要存最核心的边界和硬约束是精华部分。大部分日常问题看到这一层就够了。L3就是完整的长文档架构设计、需求方案这些厚东西都在这。只有前面几层都讲不清的时候才会翻到这。这么一套下来大部分问题前两层就解决了省老多上下文了。4 路由入口为啥要单独整个manifest文件可能有人问直接把所有规则塞一个JSON里不行吗还真不行。我们专门整个manifest-routing.json当入口里面只存关系不存具体内容。4.1 这里面装了三种关系第一种是任务对应到匹配规则和主题你说啥任务我就找对应的关键词和主题。第二种是主题id对应到实际文件路径找得到地方。第三种是主题之间的依赖关系读这个主题之前得先读哪几个前置的。就这么个薄薄的索引文件啥内容都不塞就管指路。4.2 关键词为啥要拆成小分片关键词我们没全塞索引里全拆成一个个独立的matcher文件了。为啥这么干你想啊要是全塞一个文件里改一个关键词整个文件都变Git diff全是乱的。拆成小分片改哪片动哪片互不干扰。AI也不用一上来就读所有关键词按需打开对应分片就行。当然这也不是说语义检索就没用了这是个确定性的仓内协议。像权限、幂等、数据边界这种事儿可不能靠“大概相似”就命中稳比快重要。5 匹配上了可不敢直接就干活很多人做知识路由匹配到主题就直接输出答案了。这其实很容易出问题。就像你听到有人说“退款”就直接把退款规则甩过去人家可能问的是并发冲突呢5.1 我们拆成了四步走完整的流程是四步匹配、展开依赖、检查缺口、再执行。一步都不能少。第一步匹配先把候选范围缩小别大海捞针。第二步展开依赖主主题相关的前置知识都得补上缺了前提说啥都白搭。第三步检查缺口最关键的一步。看看现有的知识到底能不能回答用户的问题不够就继续翻长文档、翻源码连需求都没说清的就得先问用户。很多工具就省了这一步检索到点相关的就敢瞎答不出错才怪。第四步才是真的干活回答问题、改代码、提交变更。说白了检索只解决“可能有关系”检查缺口才解决“能不能干活”。6 主题文件为啥只写精简事实你打开我们的topic文件都特别短。前面是元数据正文就写最核心的硬约束和下钻入口绝不写废话。6.1 短了才好组合为啥不写全写太长了一次就塞不了几个主题组合起来费劲。短一点一次任务能拼好几个相关主题信息密度还高。详细的背景和完整方案都扔L3长文档里需要再看。还有个坑得提醒大家写摘要千万别写宣传语。啥“强大高效、智能灵活”半毛钱用没有。就老老实实写清楚这是啥、管啥用、有啥限制。比啥都强。7 知识写完了咋存回去才不打架光读还不行AI写代码的时候经常会从源码里挖出来新规则。比如退款只能原路返回某个锁超时时间是10分钟。这些东西要是只留在当前会话里下次还得重新找。7.1 直接改文件多人协作必炸直接让AI改主题文件当然简单俩人同时改就出事了。Git只能看出来文本变了不知道你改的是啥意图。更坑的是文本能自动合并不代表业务规则不冲突。一个写3天到账一个写7天到账Git说没冲突到时候业务就炸了。7.2 我们整了个结构化变更文件所以我们不让直接改主题先写成结构化的kb-delta.json。里面记清楚是谁改的、基于哪个版本改的、改了啥内容、为啥改。目前就允许四种操作追加内容、替换正文、更新元数据、新建主题。动作少好处多。工具能提前校验对不对评审的时候也一眼能看明白这次改了啥、为啥改。7.3 用版本号拦住过期修改每个主题都有个版本号你改的时候基于哪个版本都记在delta里。等真正要写入的时候先比对一下当前文件的版本号。对上了就能写写完版本号加一。对不上就直接停让你先读最新的内容再说。就这么个简单的乐观锁能拦住大半的过期写入。有人说为啥不做自动合并文本能拼到一起业务规则可不能瞎拼。俩规则冲不冲突得懂业务的人来判断机器瞎掺和只会添乱。当然这东西也不是万能的它就是个磁盘层面的锁你直接手改文件它管不着正常的Git同步、代码评审也不能省。它的作用就是把冲突尽量提前暴露别等到上线了才炸。8 个人任务和团队知识为啥要分开多人用AI开发的时候仓库里会有两种东西。一种是个人的干活进度比如我这轮会话做到哪了、还有啥待办。一种是团队公认的业务规则所有人都得遵守。8.1 放一起必乱要是全提交Git个人的待办、临时笔记天天冲突烦都烦死。要是全放本地好不容易整理出来的业务知识又没法共享。所以我们就划了条线个人任务现场放.task目录下默认不进Git自己用着方便。团队公认的知识放.Knowledge目录跟着代码一起进Git、走评审。团队看进度还是靠PR、commit、issue这些老办法不搞另一套花里胡哨的。9 实际跑了一圈啥感受说再多也没用得实际试试。我找了个空仓库跑了下初始化命令。一套下来知识库目录、配置文件、入口文件都生成好了该忽略的也加进gitignore了。八项检查全过没警告没错误。但说实话这只能说明架子搭起来了好不好用还两说。路由准不准最终还是看你主题写得清不清楚、关键词覆没覆盖日常说法、代码变了知识跟没跟上。工具就是个架子内容还得靠人维护。10 这方案也不是万能的实话实说这套东西不是零成本也不是啥项目都适合。首先触发词是显式写的好处是结果透明好排查坏处是遇到没人想到的说法就可能召回不到。该用全文搜索兜底的时候还得用。其次主题拆分是个学问。拆太大并发修改容易冲突拆太细依赖关系绕得头疼。比较靠谱的拆法是按业务约束来一组稳定的、能独立判断的规则放一个主题别按文件数量瞎拆。再有知识这东西最终准不准还是得靠代码、测试和人确认。版本号、校验工具这些都是管理手段不能把瞎猜的东西变成事实。最后小项目真没必要搞这套。就几个文件的个人项目写个简洁的规则文件比啥都强。只有当团队大了、重复搜索多了、上下文漂移、知识冲突开始费钱了这套分层路由才值当去维护。11 最后唠两句其实说白了让AI懂项目不是把越多文本塞给它越好。核心是四件事怎么快速找到相关的、怎么把依赖补全、怎么判断信息够不够、怎么安全地把新知识存回去。我们现在这套思路总结下来就是三点用分层结构做渐进式知识投喂别一下塞爆把缺口检查放在执行前面别匹配到就瞎干用结构化变更和版本号管好多人协作别乱改一通。当然这方案也还在打磨还有不少问题要验证。但有一点我觉得是没错的项目上下文不该只是提示词里的一段文字它应该是能被版本控制、能持续维护的工程资产。毕竟代码是资产知识凭啥不是呢P.S. 无意间发现了一个巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/qq_34419312