作为这两年最受关注的AI编程工具Codex和Claude Code的体验我已经在不同规模的项目里实测了很长时间。无论是OpenAI官方的Codex CLI还是Anthropic的Claude Code它们确实能帮你写不少代码但真到了接手一个几十万行、多模块、纵向依赖复杂的存量工程时你会发现一个很现实的问题AI虽然能写但它经常看不见全局。我最近一直在折腾的一类东西——架构分析Skill就是专门解决这个痛点的。这类Skill里最有代表性的一套方案就是Birdview它把代码库的鸟瞰图模块边界、依赖方向、核心链路转成结构化上下文喂给Codex或Claude Code让它们在动手之前先读懂整个项目。这篇内容我会从为什么需要、Skill机制怎么工作、Birdview怎么接入到踩坑记录和扩展思路完整走一遍。适合正在用Codex、Claude Code做中大型项目的开发者也适合想给自己的团队沉淀一套AI编码规范或者说Agent工作流的人来参考。1. 从能写代码到能看懂架构AI Coding缺的不只是上下文1.1 三个名词三种角色Codex、Claude Code、Birdview分别解决什么问题很多朋友第一次看到Codex和Claude Code架构分析Skill推荐Birdview如何接入AI Coding这个标题八成会一脸懵这三个东西到底是啥关系我用大白话先把分工理清楚。Codex是OpenAI的编程智能体工具主要走CLI和IDE插件两条路。你给它一个任务它会在终端里自己定位相关文件、改写代码、跑测试甚至调用命令行工具完成一系列操作。Claude Code是Anthropic的对位产品同样以终端Agent为主多步任务编排能力很突出。这两个工具代表的就是当前最主流的AI Coding Agent不是帮你补全几行代码的插件而是能自己动手把一个小功能做完的程序员实习生。那Birdview是什么它不是编程工具也不替代Codex或者Claude Code。它是一套架构视角的注入方案——把项目的模块划分、依赖方向、核心链路这些信息整理成结构化文档再通过Skill机制塞给AI Agent。说白了Birdview提供的是一张项目地图让Agent知道自己站在哪、能往哪走、哪些地方不能碰。1.2 AI Agent为什么总是只见树木不见森林这个问题的根源在于Agent的信息获取方式是按需翻文件。虽然Codex和Claude Code支持你指定目录、指定文件但如果没有架构指引Agent大多数时候是猜的。猜中相关文件效率就高猜不中它就会在整个仓库里到处乱逛既浪费时间又消耗上下文。举一个我真实踩过的例子。一个Spring Boot老项目里订单服务被支付服务AppService引用支付服务又被对账任务引用而对账任务挂在Quartz调度里。我让Claude Code改一段对账逻辑它翻了半天锁定了一个看似相关的Mapper实际上真正的核心逻辑在更上层的聚合服务里。它改出来的代码依赖层级全错了编译都过不去。这不是模型笨而是信息不对称。Agent只看到了它打开的局部文件没看到整个调用链。如果当时有一份架构摘要告诉它对账流程的入口在X调度核心实现在Y聚合服务数据访问必须走Z仓储接口它根本不会走弯路。1.3 架构分析Skill能解决哪些实际问题说白了Birdview这类Skill解决的是AI Coding中视野的问题。具体到实际工作它能帮上忙的场景不少新同学接手存量项目先让Agent基于架构文档出一份技术分析替代逐行通读做跨模块改造给AI画好依赖边界防止它越过Service层直捣数据库同时跑多个Agent分工协作让它们共用一份架构事实避免各说各话代码评审环节让AI基于架构约束给出意见而不是只看单文件代码风格如果你只是在玩具项目或者绿地里跑AI Coding这东西可能用不上。但只要是在存量工程里干活架构上下文几乎是刚需。模型能力越强越容易在局部代码上自信地写出全局错误——这正是架构分析Skill存在的意义。2. Skill机制拆解Codex和Claude Code的能力扩展方式有什么不同2.1 Claude Code的Skill体系CLAUDE.md、Skill目录和Slash CommandClaude Code的能力扩展很多人只知道一个CLAUDE.md。确实这个文件是Claude Code的项目宪法Agent启动后会自动读取里面可以写项目结构、编码规范、架构约束、常用命令。但Claude Code的Skill能力远不止这一个文件。社区里常用的做法是把Skill做成一个目录里面放SKILL.md和配套的参考文档。SKILL.md定义这个Skill的用途、触发条件、执行步骤和输出格式有点像给Agent写的一份岗位说明书。再加上自定义Slash Command比如/birdview用户输入这个命令就直接触发架构分析流程。这套机制玩到深处还能配合Claude Code的Agent模式做任务编排。比如一个复杂改造任务Agent可以按顺序调用架构分析Skill先理解现状调用迁移方案Skill生成计划再调用代码生成Skill落地实现。每个Skill各司其职比把所有指令堆在一个文件里清晰得多。2.2 Codex的Skills体系AGENTS.md和指令自动发现Codex这边机制上更像约定优于配置。它支持项目级的指令文件Agent启动时会自动发现并加载。常见的做法是把AGENTS.md放在项目根目录里面写全局规范更进阶的玩法是建一个Skills目录每个Skill一个文件夹里面包含SKILL.md和示例、参考文件。Codex的Skill在设计上强调的是让Agent在需要时能找到你——通过指令文件描述技能的存在、用途和调用方式Agent遇到对应任务时会去读取。跟Claude Code相比Codex这套更扁平写起来负担小但约束力相对弱一些。我的经验是硬性约束比如依赖红线、禁止改目录放AGENTS.md软性能力比如架构分析流程、报告模板放Skill分工更顺手。2.3 两套机制放在一起看底层的三件事完全一致Claude Code和Codex表面上的配置格式不同但Skill的本质都是三件事第一引导Agent关注什么。给Agent指定先读哪些文件、先看哪些维度这决定了它分析问题时的起点。第二限制Agent做什么。架构红线、禁止修改目录、强制使用的接口这些规则提前声明比事后纠正高效得多。第三规定Agent怎么输出。输出格式、报告模板、代码规范明确约定之后Agent产出的东西才是团队能直接用的。Birdview要接进这两套工具其实不用写两份完全不同的配置。架构摘要、模块地图、依赖规则这些内容本身是Markdown两边都能读你要做的只是分别用CLAUDE.md/AGENTS.md和Skill目录把它们组织起来。3. Birdview接入实操关键配置和逐步落地3.1 动手之前花半小时做一次架构盘点任何Skill配置都替代不了这一步你得先把自己对项目的理解转化成能写下来的结构化信息。我每次接入一个新的存量项目都会先回答下面几个问题并记录下来技术栈清单前端框架、后端框架、脚本语言、包管理器分别是什么版本是什么模块边界项目是单仓库还是多仓内部按什么维度分模块业务域、技术层、基础设施核心入口启动类、路由注册中心、定时任务调度入口、消息队列消费者入口分别在哪依赖方向请求从Web层进来之后按什么顺序流向Service、DAO、外部接口数据访问规范ORM框架、事务管理入口、连接池统一封装是什么业务层是否允许直接碰数据源特殊目录标记哪些目录是自动生成代码、哪些是第三方生成的契约文件、哪些是历史遗留不要动这份盘点结果就是后续所有架构文档的原材料。建议把结果放到.ai/skills/birdview/下面和Skill定义放一起方便维护。3.2 一套实测可用的Skill目录结构以Claude Code为例我推荐在项目根目录建.ai文件夹保持下面的结构.ai/ ├── CLAUDE.md ├── commands/ │ └── birdview.md └── skills/ └── birdview/ ├── SKILL.md ├── architecture.md └── references/ ├── module-map.md ├── dependency-rules.md └── core-flows.md解释一下各文件的分工。CLAUDE.md是全局宪法只写每次必须遵守的硬约束。architecture.md是架构摘要控制在十五行左右给Agent一个整体框架。module-map.md是模块地图记录各模块路径、职责和对外接口。dependency-rules.md是依赖规则明确谁能调用谁。core-flows.md是核心调用链路的文字版按业务场景组织。Codex侧的结构大同小异区别是全局指令文件用AGENTS.mdSkill目录可以保持同样的skills/birdview布局。这样一套资料两个工具都能复用。3.3 一份可以直接抄的SKILL.md模板下面这份模板是我在几个项目里改过几轮后固定下来的版本你按需增删即可# Skill: Birdview架构分析 ## 用途 为AI Coding Agent提供项目架构鸟瞰视图在编码任务开始前加载。 ## 触发条件 - 用户提及架构全局模块关系依赖关键词 - 任务涉及两个以上模块的改动 - 任务是排查存量代码的Bug - 当前对话还未加载过架构上下文 ## 执行步骤 1. 读取 architecture.md输出你理解的架构摘要不超过100字 2. 根据任务涉及范围选择性读取 references/module-map.md 3. 如果改动涉及数据访问必须读取 references/dependency-rules.md 4. 确认依赖边界后再开始定位和修改代码 ## 输出格式 每次输出必须包含架构影响小节 - 影响模块xxx - 依赖约束本次改动遵循/违反了哪些规则 - 风险点改动可能影响的调用方这里有个关键细节执行步骤里让Agent先输出它理解的架构摘要。这是一个校验点——你先看它对项目理解对不对再让它深入。如果摘要都偏了后面改代码必然跑偏。3.4 Codex侧的适配写法Codex这边我用AGENTS.md加同样的architecture.mdAGENTS.md的写法可以这样# 项目全局指令 1. 在开始编码前必须读取 .ai/skills/birdview/architecture.md 2. 业务层代码仅允许通过Service接口访问数据禁止直接操作Repository 3. 任何修改不得触碰 /generated 和 /third_party 目录下的文件 4. 跨模块改动必须先输出影响分析再给出代码方案区别在哪里Claude Code的CLAUDE.md和Skill配合得比较紧密Skill可以按需触发Codex对AGENTS.md这类全局指令的读取更主动所以适合放硬约束。如果你在Codex里也建了skills目录可以在AGENTS.md里加一句如需架构分析读取.ai/skills/birdview/SKILL.md引导Agent按需加载。3.5 几个值得注意的写法细节配置文件的写法直接影响Agent执行效果。我踩过几轮坑之后总结出四个值得注意的点第一架构文档别追求全追求准。我最早写过一个三千字的架构文档覆盖了所有模块的细节结果Agent表现得像没见过这份文档一样。后来精简到十五行核心信息反而每次都被正确加载使用。原因在于Token窗口有限过于冗长的信息会被Agent当成背景噪音忽略掉。第二依赖规则用允许式表述不要用禁止式。比如业务层不允许直接调用DAOAgent执行起来容易犹豫改成业务层仅允许通过Service接口访问数据Agent的执行路径就清晰很多。肯定句式比否定句式命中率高这是实测下来很明显的差异。第三给特殊目录加上醒目标记。如果项目里有自动生成代码目录、契约文件目录、历史遗留模块直接在架构文档里写明此目录为自动生成禁止修改比在全局规范里泛泛地写注意不要改错文件有效得多。第四让Agent在任务结束时自检架构合规。我习惯在SKILL.md里加一条提交改动前Agent必须检查本次改动的文件是否违反dependency-rules.md。这一步把架构约束从输入时的事前提醒变成了输出前的事后校验闭环效果很好。4. 常见问题与排查技巧实录4.1 Agent完全不读Skill文档怎么排查这是反馈最多的问题。配置了SKILL.mdAgent启动后却像没看见。我的排查顺序是一是检查文件路径和大小写。Skill目录的层级、文件名、扩展名都必须和配置里写的一致Linux环境下大小写敏感Skills和skills是两个完全不同的路径。二是确认Agent启动时是否加载了该项目根目录。如果你的终端是从项目子目录启动的部分工具可能不会自动向上发现根目录的指令文件。我一般固定在项目根目录开终端或者在配置里用绝对路径。三是在指令文件里加一句引导。比如SKILL.md开头写当任务涉及多个模块时必须先阅读本文档这样Agent在判断任务类型时更容易被触发。四是实在不行就降级把最核心的架构约束直接写进CLAUDE.md或AGENTS.md。这两个文件在Agent启动时几乎必然读取虽然灵活度差一点但兜底效果最好。硬规矩放全局分析能力放Skill这个分工越早建立越省事。4.2 上下文窗口消耗太快怎么优化架构Skill本身占用的Token不算多但Agent在理解架构之后往往还会去读很多文件来验证上下文消耗就上去了。我的优化办法是分层设计摘要层只放不变量技术栈、模块边界、依赖方向、特殊目录这些内容一屏内放下每次启动都注入。详细层按需读取module-map、core-flows这些按业务场景组织的内容放在references目录里Agent只有在任务涉及对应模块时才去读。反正SKILL.md里已经写了触发条件它不会乱翻。另外一个小技巧在SKILL.md的执行步骤里要求Agent先基于摘要输出我理解的架构摘要不超过100字。这一步能让它在展开阅读前先对齐认知避免它带着偏差去读一大堆无关文件白白浪费Token。4.3 多个Agent协作时架构认知不一致怎么办我有一段时间同时用Codex和Claude Code处理同一个项目的不同模块很快发现两边对架构的理解会有出入。比如Codex认为某个模块可以调用另一个模块Claude Code却认为不行。问题就出在两边加载的架构信息不一致。我的解决办法是在项目根目录放一份架构事实表明确标注这是唯一权威来源两个工具共用。事实表里只记录短期内不会频繁变动的硬事实技术栈清单、模块边界、依赖方向、禁止修改的目录。任何一方想改架构相关的内容必须先更新事实表再动手改代码。这样虽然多了一道手续但多Agent协作时的一致性明显好了很多。4.4 常见问题速查表症状常见原因处理办法Agent完全不读Skill路径或文件名大小写不匹配、启动目录不对核对路径在根目录启动必要时把硬约束写进全局指令读了Skill但行为没变化Skill触发条件定义太模糊把触发条件写具体加上必须禁止等强指令词架构摘要和代码实际不符架构文档长期没更新在文档里标注最后校验时间让Agent对可疑信息保持警惕输出报告格式混乱输出格式约定不严格在SKILL.md里给出明确的Markdown模板Agent改错了模块依赖规则表述不清改用允许式表述并给出具体接口名和调用路径上下文不够用一次性注入过多详情分层设计详情按需读取先让Agent输出摘要对齐5. 实操心得、角色认知和后续扩展5.1 实测中最值钱的三条经验这套方案跑了将近两个月我最有感觉的三条经验值得单独拿出来说。第一条架构文档的少即是多是真的。我把三千字的架构文档砍到十五行之后Agent的行为变化立竿见影。原因我想明白了——AI Agent和人类一样面对过量的信息会选择性忽略。你给的每一条约束都应该有明确的执行含义模棱两可的、啰嗦的、重复的内容全删。第二条Skill和全局指令要分家。全部塞进CLAUDE.mdAgent会麻木每条都读但每条都不重视全部塞进SkillAgent又经常不主动触发。最合理的方式是每次都必须要遵守的红线放全局按任务类型才需要的方法论放Skill。第三条架构合规自检是闭环的关键。只喂架构约束给Agent不要求它提交前自检约束迟早会被遗忘。加上提交前必须检查是否违反依赖规则这一步之后Agent犯的架构级错误明显减少产出的代码更像懂业务的人写的。5.2 聊几句AI Coding工程师这个角色最近经常被问到AI Coding工程师到底算不算人工智能工程师我也借这篇文章说几句个人看法。我的理解是AI Coding工程师的核心能力不在于调模型而在于三件事能把业务需求拆解成Agent可执行的任务能把团队的经验和约束沉淀成Agent能读取的规则能判断Agent产出的代码是否真正满足架构要求。这不是传统意义上的算法工程师更像是懂架构的AI流程编排者。Birdview这类架构分析Skill本质上就是这个角色最重要的生产工具之一。工具链越来越成熟之后这个岗位的价值会越来越明显。5.3 这套方案还能往哪些方向扩展Birdview目前只是把架构信息通过Skill注入Agent路径已经跑通后续能扩的方向其实不少一是和AI Coding代码生成规范示例绑定。在Birdview的架构约束之外挂一组代码生成规范示例比如Service命名规范、事务写法模板、DTO映射方式让Agent在写新代码时直接产出符合团队约定的样板。二是在CI阶段加架构合规检查Agent。每次MR被创建时自动跑一个基于Birdview依赖规则的检查判定本次改动是否违反架构约束把人工评审的一部分工作前置到流水线里。三是让架构文档自动生成。用脚本扫描代码库里的import依赖、函数调用关系定期刷新module-map.md让鸟瞰图始终同步最新代码状态。这一步做完之后人工维护架构文档的成本会降到最低。我个人对AI Coding的看法很简单代码生成能力会越来越普及真正拉开差距的是谁能让Agent带着架构理解去写代码。Birdview这种架构分析Skill就是往这个方向走的第一步。如果你正在用Codex或Claude Code碰存量项目我建议先配一个最小版本一份十五行架构摘要一个SKILL.md要求Agent在动手前先讲清楚它理解的全局。跑一次你就会发现AI的靠谱程度真的不是只靠模型版本而是靠你给它的视野够不够。 
长河君 · 2026/11/4 3:41:45 · 阅读 1.2k Codex与Claude Code架构分析Skill：用Birdview为AI编程提供全局视野
作为这两年最受关注的AI编程工具Codex和Claude Code的体验我已经在不同规模的项目里实测了很长时间。无论是OpenAI官方的Codex CLI还是Anthropic的Claude Code它们确实能帮你写不少代码但真到了接手一个几十万行、多模块、纵向依赖复杂的存量工程时你会发现一个很现实的问题AI虽然能写但它经常看不见全局。我最近一直在折腾的一类东西——架构分析Skill就是专门解决这个痛点的。这类Skill里最有代表性的一套方案就是Birdview它把代码库的鸟瞰图模块边界、依赖方向、核心链路转成结构化上下文喂给Codex或Claude Code让它们在动手之前先读懂整个项目。这篇内容我会从为什么需要、Skill机制怎么工作、Birdview怎么接入到踩坑记录和扩展思路完整走一遍。适合正在用Codex、Claude Code做中大型项目的开发者也适合想给自己的团队沉淀一套AI编码规范或者说Agent工作流的人来参考。1. 从能写代码到能看懂架构AI Coding缺的不只是上下文1.1 三个名词三种角色Codex、Claude Code、Birdview分别解决什么问题很多朋友第一次看到Codex和Claude Code架构分析Skill推荐Birdview如何接入AI Coding这个标题八成会一脸懵这三个东西到底是啥关系我用大白话先把分工理清楚。Codex是OpenAI的编程智能体工具主要走CLI和IDE插件两条路。你给它一个任务它会在终端里自己定位相关文件、改写代码、跑测试甚至调用命令行工具完成一系列操作。Claude Code是Anthropic的对位产品同样以终端Agent为主多步任务编排能力很突出。这两个工具代表的就是当前最主流的AI Coding Agent不是帮你补全几行代码的插件而是能自己动手把一个小功能做完的程序员实习生。那Birdview是什么它不是编程工具也不替代Codex或者Claude Code。它是一套架构视角的注入方案——把项目的模块划分、依赖方向、核心链路这些信息整理成结构化文档再通过Skill机制塞给AI Agent。说白了Birdview提供的是一张项目地图让Agent知道自己站在哪、能往哪走、哪些地方不能碰。1.2 AI Agent为什么总是只见树木不见森林这个问题的根源在于Agent的信息获取方式是按需翻文件。虽然Codex和Claude Code支持你指定目录、指定文件但如果没有架构指引Agent大多数时候是猜的。猜中相关文件效率就高猜不中它就会在整个仓库里到处乱逛既浪费时间又消耗上下文。举一个我真实踩过的例子。一个Spring Boot老项目里订单服务被支付服务AppService引用支付服务又被对账任务引用而对账任务挂在Quartz调度里。我让Claude Code改一段对账逻辑它翻了半天锁定了一个看似相关的Mapper实际上真正的核心逻辑在更上层的聚合服务里。它改出来的代码依赖层级全错了编译都过不去。这不是模型笨而是信息不对称。Agent只看到了它打开的局部文件没看到整个调用链。如果当时有一份架构摘要告诉它对账流程的入口在X调度核心实现在Y聚合服务数据访问必须走Z仓储接口它根本不会走弯路。1.3 架构分析Skill能解决哪些实际问题说白了Birdview这类Skill解决的是AI Coding中视野的问题。具体到实际工作它能帮上忙的场景不少新同学接手存量项目先让Agent基于架构文档出一份技术分析替代逐行通读做跨模块改造给AI画好依赖边界防止它越过Service层直捣数据库同时跑多个Agent分工协作让它们共用一份架构事实避免各说各话代码评审环节让AI基于架构约束给出意见而不是只看单文件代码风格如果你只是在玩具项目或者绿地里跑AI Coding这东西可能用不上。但只要是在存量工程里干活架构上下文几乎是刚需。模型能力越强越容易在局部代码上自信地写出全局错误——这正是架构分析Skill存在的意义。2. Skill机制拆解Codex和Claude Code的能力扩展方式有什么不同2.1 Claude Code的Skill体系CLAUDE.md、Skill目录和Slash CommandClaude Code的能力扩展很多人只知道一个CLAUDE.md。确实这个文件是Claude Code的项目宪法Agent启动后会自动读取里面可以写项目结构、编码规范、架构约束、常用命令。但Claude Code的Skill能力远不止这一个文件。社区里常用的做法是把Skill做成一个目录里面放SKILL.md和配套的参考文档。SKILL.md定义这个Skill的用途、触发条件、执行步骤和输出格式有点像给Agent写的一份岗位说明书。再加上自定义Slash Command比如/birdview用户输入这个命令就直接触发架构分析流程。这套机制玩到深处还能配合Claude Code的Agent模式做任务编排。比如一个复杂改造任务Agent可以按顺序调用架构分析Skill先理解现状调用迁移方案Skill生成计划再调用代码生成Skill落地实现。每个Skill各司其职比把所有指令堆在一个文件里清晰得多。2.2 Codex的Skills体系AGENTS.md和指令自动发现Codex这边机制上更像约定优于配置。它支持项目级的指令文件Agent启动时会自动发现并加载。常见的做法是把AGENTS.md放在项目根目录里面写全局规范更进阶的玩法是建一个Skills目录每个Skill一个文件夹里面包含SKILL.md和示例、参考文件。Codex的Skill在设计上强调的是让Agent在需要时能找到你——通过指令文件描述技能的存在、用途和调用方式Agent遇到对应任务时会去读取。跟Claude Code相比Codex这套更扁平写起来负担小但约束力相对弱一些。我的经验是硬性约束比如依赖红线、禁止改目录放AGENTS.md软性能力比如架构分析流程、报告模板放Skill分工更顺手。2.3 两套机制放在一起看底层的三件事完全一致Claude Code和Codex表面上的配置格式不同但Skill的本质都是三件事第一引导Agent关注什么。给Agent指定先读哪些文件、先看哪些维度这决定了它分析问题时的起点。第二限制Agent做什么。架构红线、禁止修改目录、强制使用的接口这些规则提前声明比事后纠正高效得多。第三规定Agent怎么输出。输出格式、报告模板、代码规范明确约定之后Agent产出的东西才是团队能直接用的。Birdview要接进这两套工具其实不用写两份完全不同的配置。架构摘要、模块地图、依赖规则这些内容本身是Markdown两边都能读你要做的只是分别用CLAUDE.md/AGENTS.md和Skill目录把它们组织起来。3. Birdview接入实操关键配置和逐步落地3.1 动手之前花半小时做一次架构盘点任何Skill配置都替代不了这一步你得先把自己对项目的理解转化成能写下来的结构化信息。我每次接入一个新的存量项目都会先回答下面几个问题并记录下来技术栈清单前端框架、后端框架、脚本语言、包管理器分别是什么版本是什么模块边界项目是单仓库还是多仓内部按什么维度分模块业务域、技术层、基础设施核心入口启动类、路由注册中心、定时任务调度入口、消息队列消费者入口分别在哪依赖方向请求从Web层进来之后按什么顺序流向Service、DAO、外部接口数据访问规范ORM框架、事务管理入口、连接池统一封装是什么业务层是否允许直接碰数据源特殊目录标记哪些目录是自动生成代码、哪些是第三方生成的契约文件、哪些是历史遗留不要动这份盘点结果就是后续所有架构文档的原材料。建议把结果放到.ai/skills/birdview/下面和Skill定义放一起方便维护。3.2 一套实测可用的Skill目录结构以Claude Code为例我推荐在项目根目录建.ai文件夹保持下面的结构.ai/ ├── CLAUDE.md ├── commands/ │ └── birdview.md └── skills/ └── birdview/ ├── SKILL.md ├── architecture.md └── references/ ├── module-map.md ├── dependency-rules.md └── core-flows.md解释一下各文件的分工。CLAUDE.md是全局宪法只写每次必须遵守的硬约束。architecture.md是架构摘要控制在十五行左右给Agent一个整体框架。module-map.md是模块地图记录各模块路径、职责和对外接口。dependency-rules.md是依赖规则明确谁能调用谁。core-flows.md是核心调用链路的文字版按业务场景组织。Codex侧的结构大同小异区别是全局指令文件用AGENTS.mdSkill目录可以保持同样的skills/birdview布局。这样一套资料两个工具都能复用。3.3 一份可以直接抄的SKILL.md模板下面这份模板是我在几个项目里改过几轮后固定下来的版本你按需增删即可# Skill: Birdview架构分析 ## 用途 为AI Coding Agent提供项目架构鸟瞰视图在编码任务开始前加载。 ## 触发条件 - 用户提及架构全局模块关系依赖关键词 - 任务涉及两个以上模块的改动 - 任务是排查存量代码的Bug - 当前对话还未加载过架构上下文 ## 执行步骤 1. 读取 architecture.md输出你理解的架构摘要不超过100字 2. 根据任务涉及范围选择性读取 references/module-map.md 3. 如果改动涉及数据访问必须读取 references/dependency-rules.md 4. 确认依赖边界后再开始定位和修改代码 ## 输出格式 每次输出必须包含架构影响小节 - 影响模块xxx - 依赖约束本次改动遵循/违反了哪些规则 - 风险点改动可能影响的调用方这里有个关键细节执行步骤里让Agent先输出它理解的架构摘要。这是一个校验点——你先看它对项目理解对不对再让它深入。如果摘要都偏了后面改代码必然跑偏。3.4 Codex侧的适配写法Codex这边我用AGENTS.md加同样的architecture.mdAGENTS.md的写法可以这样# 项目全局指令 1. 在开始编码前必须读取 .ai/skills/birdview/architecture.md 2. 业务层代码仅允许通过Service接口访问数据禁止直接操作Repository 3. 任何修改不得触碰 /generated 和 /third_party 目录下的文件 4. 跨模块改动必须先输出影响分析再给出代码方案区别在哪里Claude Code的CLAUDE.md和Skill配合得比较紧密Skill可以按需触发Codex对AGENTS.md这类全局指令的读取更主动所以适合放硬约束。如果你在Codex里也建了skills目录可以在AGENTS.md里加一句如需架构分析读取.ai/skills/birdview/SKILL.md引导Agent按需加载。3.5 几个值得注意的写法细节配置文件的写法直接影响Agent执行效果。我踩过几轮坑之后总结出四个值得注意的点第一架构文档别追求全追求准。我最早写过一个三千字的架构文档覆盖了所有模块的细节结果Agent表现得像没见过这份文档一样。后来精简到十五行核心信息反而每次都被正确加载使用。原因在于Token窗口有限过于冗长的信息会被Agent当成背景噪音忽略掉。第二依赖规则用允许式表述不要用禁止式。比如业务层不允许直接调用DAOAgent执行起来容易犹豫改成业务层仅允许通过Service接口访问数据Agent的执行路径就清晰很多。肯定句式比否定句式命中率高这是实测下来很明显的差异。第三给特殊目录加上醒目标记。如果项目里有自动生成代码目录、契约文件目录、历史遗留模块直接在架构文档里写明此目录为自动生成禁止修改比在全局规范里泛泛地写注意不要改错文件有效得多。第四让Agent在任务结束时自检架构合规。我习惯在SKILL.md里加一条提交改动前Agent必须检查本次改动的文件是否违反dependency-rules.md。这一步把架构约束从输入时的事前提醒变成了输出前的事后校验闭环效果很好。4. 常见问题与排查技巧实录4.1 Agent完全不读Skill文档怎么排查这是反馈最多的问题。配置了SKILL.mdAgent启动后却像没看见。我的排查顺序是一是检查文件路径和大小写。Skill目录的层级、文件名、扩展名都必须和配置里写的一致Linux环境下大小写敏感Skills和skills是两个完全不同的路径。二是确认Agent启动时是否加载了该项目根目录。如果你的终端是从项目子目录启动的部分工具可能不会自动向上发现根目录的指令文件。我一般固定在项目根目录开终端或者在配置里用绝对路径。三是在指令文件里加一句引导。比如SKILL.md开头写当任务涉及多个模块时必须先阅读本文档这样Agent在判断任务类型时更容易被触发。四是实在不行就降级把最核心的架构约束直接写进CLAUDE.md或AGENTS.md。这两个文件在Agent启动时几乎必然读取虽然灵活度差一点但兜底效果最好。硬规矩放全局分析能力放Skill这个分工越早建立越省事。4.2 上下文窗口消耗太快怎么优化架构Skill本身占用的Token不算多但Agent在理解架构之后往往还会去读很多文件来验证上下文消耗就上去了。我的优化办法是分层设计摘要层只放不变量技术栈、模块边界、依赖方向、特殊目录这些内容一屏内放下每次启动都注入。详细层按需读取module-map、core-flows这些按业务场景组织的内容放在references目录里Agent只有在任务涉及对应模块时才去读。反正SKILL.md里已经写了触发条件它不会乱翻。另外一个小技巧在SKILL.md的执行步骤里要求Agent先基于摘要输出我理解的架构摘要不超过100字。这一步能让它在展开阅读前先对齐认知避免它带着偏差去读一大堆无关文件白白浪费Token。4.3 多个Agent协作时架构认知不一致怎么办我有一段时间同时用Codex和Claude Code处理同一个项目的不同模块很快发现两边对架构的理解会有出入。比如Codex认为某个模块可以调用另一个模块Claude Code却认为不行。问题就出在两边加载的架构信息不一致。我的解决办法是在项目根目录放一份架构事实表明确标注这是唯一权威来源两个工具共用。事实表里只记录短期内不会频繁变动的硬事实技术栈清单、模块边界、依赖方向、禁止修改的目录。任何一方想改架构相关的内容必须先更新事实表再动手改代码。这样虽然多了一道手续但多Agent协作时的一致性明显好了很多。4.4 常见问题速查表症状常见原因处理办法Agent完全不读Skill路径或文件名大小写不匹配、启动目录不对核对路径在根目录启动必要时把硬约束写进全局指令读了Skill但行为没变化Skill触发条件定义太模糊把触发条件写具体加上必须禁止等强指令词架构摘要和代码实际不符架构文档长期没更新在文档里标注最后校验时间让Agent对可疑信息保持警惕输出报告格式混乱输出格式约定不严格在SKILL.md里给出明确的Markdown模板Agent改错了模块依赖规则表述不清改用允许式表述并给出具体接口名和调用路径上下文不够用一次性注入过多详情分层设计详情按需读取先让Agent输出摘要对齐5. 实操心得、角色认知和后续扩展5.1 实测中最值钱的三条经验这套方案跑了将近两个月我最有感觉的三条经验值得单独拿出来说。第一条架构文档的少即是多是真的。我把三千字的架构文档砍到十五行之后Agent的行为变化立竿见影。原因我想明白了——AI Agent和人类一样面对过量的信息会选择性忽略。你给的每一条约束都应该有明确的执行含义模棱两可的、啰嗦的、重复的内容全删。第二条Skill和全局指令要分家。全部塞进CLAUDE.mdAgent会麻木每条都读但每条都不重视全部塞进SkillAgent又经常不主动触发。最合理的方式是每次都必须要遵守的红线放全局按任务类型才需要的方法论放Skill。第三条架构合规自检是闭环的关键。只喂架构约束给Agent不要求它提交前自检约束迟早会被遗忘。加上提交前必须检查是否违反依赖规则这一步之后Agent犯的架构级错误明显减少产出的代码更像懂业务的人写的。5.2 聊几句AI Coding工程师这个角色最近经常被问到AI Coding工程师到底算不算人工智能工程师我也借这篇文章说几句个人看法。我的理解是AI Coding工程师的核心能力不在于调模型而在于三件事能把业务需求拆解成Agent可执行的任务能把团队的经验和约束沉淀成Agent能读取的规则能判断Agent产出的代码是否真正满足架构要求。这不是传统意义上的算法工程师更像是懂架构的AI流程编排者。Birdview这类架构分析Skill本质上就是这个角色最重要的生产工具之一。工具链越来越成熟之后这个岗位的价值会越来越明显。5.3 这套方案还能往哪些方向扩展Birdview目前只是把架构信息通过Skill注入Agent路径已经跑通后续能扩的方向其实不少一是和AI Coding代码生成规范示例绑定。在Birdview的架构约束之外挂一组代码生成规范示例比如Service命名规范、事务写法模板、DTO映射方式让Agent在写新代码时直接产出符合团队约定的样板。二是在CI阶段加架构合规检查Agent。每次MR被创建时自动跑一个基于Birdview依赖规则的检查判定本次改动是否违反架构约束把人工评审的一部分工作前置到流水线里。三是让架构文档自动生成。用脚本扫描代码库里的import依赖、函数调用关系定期刷新module-map.md让鸟瞰图始终同步最新代码状态。这一步做完之后人工维护架构文档的成本会降到最低。我个人对AI Coding的看法很简单代码生成能力会越来越普及真正拉开差距的是谁能让Agent带着架构理解去写代码。Birdview这种架构分析Skill就是往这个方向走的第一步。如果你正在用Codex或Claude Code碰存量项目我建议先配一个最小版本一份十五行架构摘要一个SKILL.md要求Agent在动手前先讲清楚它理解的全局。跑一次你就会发现AI的靠谱程度真的不是只靠模型版本而是靠你给它的视野够不够。