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 Command

Claude 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.md，Skill目录可以保持同样的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.md，AGENTS.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当成背景噪音忽略掉。

第二，依赖规则用"允许式"表述，不要用"禁止式"。比如"业务层不允许直接调用DAO"，Agent执行起来容易犹豫；改成"业务层仅允许通过Service接口访问数据"，Agent的执行路径就清晰很多。肯定句式比否定句式命中率高，这是实测下来很明显的差异。

第三，给特殊目录加上醒目标记。如果项目里有自动生成代码目录、契约文件目录、历史遗留模块，直接在架构文档里写明"此目录为自动生成，禁止修改"，比在全局规范里泛泛地写"注意不要改错文件"有效得多。

第四，让Agent在任务结束时自检架构合规。我习惯在SKILL.md里加一条：提交改动前，Agent必须检查本次改动的文件是否违反dependency-rules.md。这一步把架构约束从"输入时的事前提醒"变成了"输出前的事后校验"，闭环效果很好。

4. 常见问题与排查技巧实录

4.1 Agent完全不读Skill文档，怎么排查

这是反馈最多的问题。配置了SKILL.md，Agent启动后却像没看见。我的排查顺序是：

一是检查文件路径和大小写。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 常见问题速查表

5. 实操心得、角色认知和后续扩展

5.1 实测中最值钱的三条经验

这套方案跑了将近两个月，我最有感觉的三条经验，值得单独拿出来说。

第一条：架构文档的"少即是多"是真的。我把三千字的架构文档砍到十五行之后，Agent的行为变化立竿见影。原因我想明白了——AI Agent和人类一样，面对过量的信息会选择性忽略。你给的每一条约束都应该有明确的执行含义，模棱两可的、啰嗦的、重复的内容，全删。

第二条：Skill和全局指令要分家。全部塞进CLAUDE.md，Agent会麻木，每条都读但每条都不重视；全部塞进Skill，Agent又经常不主动触发。最合理的方式是：每次都必须要遵守的红线放全局，按任务类型才需要的方法论放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的靠谱程度，真的不是只靠模型版本，而是靠你给它的视野够不够。