1. 为什么AI Coding需要"上帝视角"：从单文件补全到全仓理解
这两年AI编程工具的发展脉络其实非常清晰。最早大家用的是自动补全，Cursor出来之后变成了多行生成、跨文件编辑，而到了Codex和Claude Code这一代，已经彻底进化成了"代理式编程"——你只需要在终端里描述需求，AI自己会规划任务、搜索代码、修改文件、运行测试，甚至反复迭代直到通过。
听起来很美好，对吧？但实际用下来你会发现一个致命问题：AI对项目的理解是碎片化的。它在当前会话里看到的是最近打开的若干文件，或者通过grep检索到的一堆片段，它并不知道你的项目整体长什么样。这就像让一个新同事修一个几十万行的老系统，你只给他看几个出问题的函数，却不告诉他这些函数在哪个模块、被谁调用、依赖哪些服务——他能修好单个Bug，但遇到跨模块的架构级改造，基本就是瞎猜。
我最初用Claude Code做一次全局重构时栽过大跟头。AI自信满满地修改了一个公共函数签名，结果全项目几十处调用点全部编译失败。它不是不聪明，是压根不知道那个函数被多少地方引用。也就是从那次之后我开始意识到：AI Coding的未来不在于模型多聪明，而在于你能不能把"项目全貌"有效喂给它。
这就是Birdview这类架构分析思路的价值所在。所谓Birdview，直译就是"鸟瞰视角"，放到AI编程场景里，它的作用只有一个：在你让AI动手之前，先帮AI建立起对整个项目的完整认知——模块划分、依赖关系、数据流向、技术栈分布、潜在的架构约束。相当于在AI进入代码库之前，先给它一张准确的地图。
这篇文章我会重点做三件事：第一，拆解Codex和Claude Code的Skill机制到底是什么，为什么这是接入架构分析的最佳入口；第二，完整展示一套Birdview架构分析Skill的设计思路和核心脚本逻辑；第三，手把手演示怎么把它装进Codex和Claude Code里，以及我在实际操作中踩过的坑和排查经验。
适合谁来参考？如果你正在重度使用Codex或Claude Code做真实项目开发，尤其是维护中大型代码库、经常需要让AI做跨模块改造，这篇文章值得看完。如果你还停留在"让AI写点小函数"的阶段，也可以借此理解下一代AI编程的工作方式——授人以鱼不如授人以渔，架构感知能力就是那张"渔网"。
2. Skill机制拆解：AI从"能用"到"会用"的临门一脚
2.1 什么是Agent Skill，它解决什么问题
先梳理一个概念。Codex和Claude Code这类工具本质上是一个"会写代码的对话Agent"，但它们的能力边界很大程度取决于你是否给了它们正确的"技能"。所谓Skill，通俗讲就是一套结构化的指令包，里面包含了某个专业任务的执行步骤、判断标准、模板和工具调用方式。
为什么需要这套东西？因为底层的通用模型虽然推理能力强，但它不知道你的团队约定、你的框架版本、你的项目结构、你的常见坑位。Skill就是用来弥补这个信息差的——把"资深工程师做某类任务时的经验和流程"沉淀下来，变成AI可以加载的方法论。
举一个最直观的例子。没有Skill的Claude Code，遇到"帮我把这个报错处理一下"这样的需求时，它会按照通用经验回答，大概率是搜一下异常类型、看一下堆栈、改一下代码。但如果你的项目里有一套统一错误码规范、有一个集中式异常上报系统、甚至要求所有对外接口返回统一格式，通用模型根本不知道这些。而你要是写了一个"错误处理Skill"，AI就会被引导着先去查错误码表，再定位到对应的错误处理模块，最后按规范生成代码。
Skill这个东西现在各家平台都有类似的实现。Claude Code在较新的版本中开始支持~/.claude/skills/目录下的自定义Skill，通过SKILL.md文件声明；Codex也在逐步跟进，支持通过配置文件或指令加载类似的技能包。核心机制大同小异，都是渐进式披露：平时不占用上下文，需要时AI主动读取对应技能文件，按里面的步骤执行。
2.2 Skill、Prompt和MCP：三者到底什么关系
很多刚接触的朋友会把Skill和Prompt搞混。简单区分一下：
- Prompt是一次性的对话指令，用完即弃，没有沉淀价值。你每次换新会话，都得重新把所有背景、要求讲一遍。
- Skill是可复用的、结构化的方法论文档，存放在固定路径，AI可以根据任务自动决定是否加载。它是有"记忆"的。
- MCP（Model Context Protocol）是一个标准化协议，让AI调用外部工具和数据源。Skill定义"怎么做"，MCP解决"用什么拿数据"。
三者并不冲突，实际使用中经常组合。以Birdview为例，理论上你可以用MCP写一个服务，给AI暴露项目结构查询接口；也可以更轻量地，把架构分析逻辑封装成几个脚本，再由Skill来编排调用，脚本产出的结果作为上下文反馈给模型。我个人更推荐后者，原因后面在实操部分会详细讲。
2.3 Skill生态现状：Claude Code和Codex各自的玩法
先说Claude Code。它目前支持将Skill放置在~/.claude/skills/目录下，或者项目级.claude/skills/目录中。每个技能就是一个文件夹，里面至少包含一个SKILL.md文件，声明技能名称、描述、适用场景和执行步骤。AI在对话中会根据用户需求自动判断是否加载对应的技能定义，然后严格按里面的指令执行。
Codex这边，它的Skill机制仍在快速演进。早期版本的Codex更多依赖AGENTS.md这种项目说明文件——相当于给AI的"项目简报"。但现在的Codex也支持类似技能包的做法，你可以在~/.codex/下放自定义指令集，或者在项目里用特定的markdown文件组织规则。两者思路相通：核心不是文件格式，而是你如何结构化地告诉AI"遇到什么任务、按什么流程做"。
有一段时间社区里讨论最多的问题就是"这些Skill会不会互相冲突"。实际上这个担心是多余的——大多数Skill触发都有明确的适用条件，AI会先看技能描述，再决定是否调用。真正需要操心的是怎么把技能描述写得足够精准，让AI在需要的时候找得到它。
3. Birdview架构分析Skill完整设计：让AI先看地图再动手
3.1 架构分析到底要提供哪些能力
动手写Skill之前，先想清楚一个问题：你要喂给AI的"架构信息"具体包括什么？我总结下来，一套比较完整的Birdview至少应该覆盖以下维度：
模块地图。整个项目由哪些顶层模块/目录组成，每个模块的职责边界是什么。这是最基础的一层，让AI知道代码长在哪个区域，避免"改错地方"。
依赖关系。模块之间的引用关系、依赖方向、有没有循环依赖。这层信息特别关键，AI在做跨模块修改时，必须先知道改动的影响半径。
数据流/调用链。核心链路的调用顺序，比如一个请求从入口Controller到Service到Repository的完整路径。没有这层认知，AI写的代码时常会在错误层级做业务逻辑，比如直接在Controller里写SQL这种离奇操作。
技术栈与关键约束。项目用了哪些框架、哪些版本、什么构建工具、代码规范是什么。AI经常会在老项目里生成新语法导致编译不过，就是因为没人告诉它约束条件。
潜在风险区域。比如某些模块长期没人维护、某个函数的圈复杂度爆炸、某些历史遗留的hack代码。AI在改造时如果不小心碰到这些区域，很容易踩雷。
这五块信息，合起来就是一张"项目体检报告"。拿到这张报告，AI才算是真正"看懂"了项目，而不是"看到"了项目。
3.2 Skill目录结构与SKILL.md设计
这一套Birdview Skill我在本地跑了一段时间，目录结构大致长这样：
birdview-skill/ ├── SKILL.md ├── scripts/ │ ├── project_map.py │ ├── dep_analyze.py │ └── context_builder.py └── templates/ ├── architecture_overview.md └── risk_report.md其中SKILL.md是整个技能的"入口说明书"，它的作用有两个：一是让AI能够识别这个技能何时适用；二是在AI决定启用后，指导它按照固定流程去操作。下面是我精简后的一个示范写法：
--- name: birdview description: 用于分析项目整体架构的全景工具。当用户要求评估系统架构、定位跨模块改造影响范围、梳理模块依赖、生成项目地图或技术债务报告时，应使用此技能。 --- # Birdview 架构分析 ## 使用场景 - 用户要求"分析整个项目""从全局视角理解系统""梳理模块依赖" - 用户准备进行跨模块重构，需要了解影响面 - 用户询问某个模块上下游关系或数据流 ## 执行流程 1. 运行 `python scripts/project_map.py` 生成基础模块地图 2. 运行 `python scripts/dep_analyze.py` 生成依赖关系报告 3. 阅读 `templates/architecture_overview.md` 了解输出要求 4. 将两份报告与项目根目录 `AGENTS.md` / `README.md` 结合，生成架构概述 5. 如果用户需要风险排查，运行 `scripts/risk_scan.py`（若有） ## 输出要求 - 模块地图必须标注各模块职责一句话说明 - 依赖分析必须明确标注循环依赖和危险引用 - 所有结论必须指向具体文件路径，禁止模糊表述一定不要小看SKILL.md里"使用场景"这部分。它直接决定了AI能不能在恰当的时候触发这个技能。我一开始写得很笼统，只写了一句"分析架构"，结果AI十次里有八次不会主动加载它。后来把场景写细、写具体，触发率才上来。这本质上是一个"技能检索的召回率"问题。
3.3 核心脚本逻辑：模块地图和依赖分析怎么实现
SKILL.md是皮，真正干活的是那几个脚本。我以Python实现为例，讲一下核心逻辑。模块地图最简单粗暴的办法是扫描目录结构，排除常见忽略项，再通过关键词识别模块职责。依赖分析稍微复杂一点，需要解析import语句或者构建工具提供的依赖信息。
依赖分析脚本的核心思路是遍历项目源码文件，提取所有import/include/require语句，建立"文件 -> 引用目标"的映射关系，再按模块归类聚合。Python项目可以用ast模块非常干净地拿到import信息，Node.js项目可以借助madge之类的工具，Java项目可以用jdeps接口。
下面这段代码是Python项目模块地图生成器的一个demo：
import os import ast from collections import defaultdict # 忽略的目录或文件 IGNORE_DIRS = {'.git', 'venv', 'node_modules', '__pycache__', 'dist', 'build'} def scan_modules(root): """扫描项目顶层模块，识别每个模块的入口文件""" modules = {} for entry in sorted(os.listdir(root)): full_path = os.path.join(root, entry) if os.path.isdir(full_path) and entry not in IGNORE_DIRS: modules[entry] = analyze_directory(full_path, entry) return modules def analyze_directory(path, mod_name): """分析单个目录，提取文件数量和大致职责关键词""" py_files = [] for dirpath, dirnames, filenames in os.walk(path): dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS] for f in filenames: if f.endswith('.py'): py_files.append(os.path.join(dirpath, f)) keywords = extract_keywords(py_files) return { 'file_count': len(py_files), 'keywords': keywords, 'dependencies': extract_dependencies(py_files) } def extract_dependencies(files): """提取模块间的引用关系""" deps = sets.defaultdict(set) for f in files: with open(f, 'r', encoding='utf-8', errors='ignore') as src: try: tree = ast.parse(src.read()) except SyntaxError: continue for node in ast.walk(tree): if isinstance(node, ast.ImportFrom) and node.module: deps[f].add(node.module.split('.')[0]) elif isinstance(node, ast.Import): for alias in node.names: deps[f].add(alias.name.split('.')[0]) return {k: v for k, v in deps.items() if v}代码本身不复杂，难的是你怎么把结果组织成"AI容易理解的语言"。我生成的报告里，每个模块会有职责关键词，依赖关系会有方向箭头标记。AI读这种半结构化的文本报告，比让它自己翻源码高效一倍不止。
3.4 为什么不用MCP、选择轻量脚本封装
我前面提到过，架构分析能力既可以用MCP实现，也可以用Skill+脚本实现。我实际两边都试过，最后长期用的是后者。原因很实在：
第一，MCP服务要常驻运行，涉及端口、鉴权、协议配置，在多个项目间切换时非常麻烦；而脚本方案只需要在Skill执行时临时调用，用完即走，零常驻成本。
第二，MCP返回的数据是结构化schema，AI读起来反而没有"一份精心排版过的markdown报告"来得直观。模型对文本的理解能力比对JSON强得多，这一点在实测中差异很明显。
第三，脚本方案的可移植性太好了。整个Skill目录直接拷到另一台机器、另一个项目，改一下根路径配置就能跑，不依赖任何环境变量或服务注册。
当然，MCP也有它的场景：如果你需要让AI实时查询Git历史、动态监控测试覆盖率、对接内部工具链，MCP是更合适的选择。一句话总结：静态分析交给Skill脚本，动态交互交给MCP，两者配合反而最舒服。
4. 从零到一：把Birdview接入Codex和Claude Code
4.1 前置准备：Codex CLI和Claude Code的安装
在开始接入之前，先确保本地环境里有Codex CLI和Claude Code命令行工具。Codex CLI当前主要通过npm安装，或者Homebrew安装。国内使用时不涉及任何网络代理问题，只需要确保登录认证通过、账号有可用额度。Claude Code也是类似的命令行工具，安装后运行claude命令进入交互式终端。
这里有一个小建议：两个工具的认证信息务必分开管理。我遇到的最常见问题就是多个账号在同一台机器上，导致工具读取了错误的token，表现就是登录无效或者额度异常。解决办法是把配置目录隔离好，Codex的认证信息在~/.codex/auth.json，Claude Code的在~/.claude/下，不要混淆。
4.2 将Birdview Skill装入Claude Code
Claude Code接入自定义Skill，路径和格式要严格遵循。在用户目录下创建：
mkdir -p ~/.claude/skills/birdview/scripts mkdir -p ~/.claude/skills/birdview/templates然后把SKILL.md放到~/.claude/skills/birdview/目录下，脚本放到scripts/子目录。完成后，在Claude Code会话中直接问一句"用birdview技能分析一下当前项目架构"，如果它正确响应，说明Skill已经被识别。
Claude Code加载Skill的机制是：会话启动时扫描技能目录，把SKILL.md的description部分作为"技能索引"放进上下文。真正到触发的时候才读取完整内容。所以前面强调的description质量，就是决定AI"知不知道有这个技能"的关键。
接入过程中有几个细节值得注意。SKILL.md里如果用了外部脚本，脚本路径建议使用相对路径，并以Skill目录为基准。因为Claude Code在子目录执行命令时，cwd不一定是你启动会话那个目录。脚本开头一律用cd "$(dirname "$0")/.."这类防御性写法，确保路径安全。
4.3 Codex接入：技能目录与规则文件的配合
Codex的Skill机制我个人体验下来，比Claude Code更依赖"规则文件"这种形式。你可以把Birdview的核心说明写进~/.codex/目录下的规则配置里，同时把项目级AGENTS.md作为触发入口。
怎么理解这个配合？AGENTS.md相当于项目的"说明书"，AI每次进入项目会话时会自动读取。我把一段话放在里面："当需要分析全局架构时，使用Birdview技能，执行~/.codex/birdview/SKILL.md中的流程。"这样一来，AI只要发现用户提问涉及架构，就会主动去找Birdview技能包。
Codex官方推荐的codex skill add之类命令在不同版本中名称可能略有不同，但思路一致。如果你用的版本不支持直接命令式添加，手动创建目录结构也完全可以。说到底，Skill的本质就是一堆约定路径下的文件，形式是服务于内容的。
4.4 实战验证：让AI做一个全局架构问答
Skill接好之后，最重要的就是验证它是否真的被AI正确使用了。我拿一个旧的电商后端项目试了一次，在Codex里发起提问："这个项目的核心交易模块是哪几个？如果我要把订单模块的数据库从MySQL迁移到PostgreSQL，会影响到哪些服务？"
没有加载Birdview之前，Codex的回答非常敷衍，基本就是从README.md里摘一点信息，然后给出一些泛泛而谈的建议。而它识别并执行了Birdview Skill之后，回答完全不一样——先输出了模块地图，标出订单、商品、用户、支付、库存五个核心域；然后从依赖分析里找到支付服务反向依赖订单服务这一条关键链路；最后明确列出了迁移需要动到的6个文件路径、2个共享的数据库访问工具类。这种级别的答案，才是真正可以直接用于评估方案的信息。
这次实测也验证了核心判断：给AI补上架构认知，它的输出质量是质变而不是量变。触发Skill前后的差别，就像让一个实习生和一个做了三年架构的工程师分别回答同一个系统设计问题。
5. 踩坑记录与Debug实录：那些文档里不会告诉你的事
5.1 SKILL.md格式问题：为什么AI没识别我的技能
我最初写Skill时遇到的最诡异问题：目录路径完全正确，SKILL.md文件也没问题，但AI死活不加载。后来逐一排查才发现，是因为SKILL.md文件里的YAML frontmatter写错了格式——我在description里用了英文冒号加引号，导致解析器把整个frontmatter当成无效内容跳过了。
这个问题的根因是YAML对格式的敏感性。description字段如果有特殊字符（比如冒号、双引号、方括号），必须用引号包起来，或者干脆避免使用这些字符。我的建议是description写得尽量像"一段可以做搜索匹配的纯文字"，不要带标点符号的花样。另外，文件编码必须UTF-8无BOM，某些Windows编辑器保存的带BOM文件会直接让解析器崩溃。
还有一个常见的坑：Skill目录名不能随便带空格和特殊字符，尽量用小写字母加下划线。有一个项目里我用的是bird-view连字符，部分版本的解析器把连字符当成了非法字符，加载失败。换成birdview之后一切正常。
5.2 上下文限制：架构报告太长怎么办
架构分析报告如果做得太详细，很容易超出模型的上下文窗口。我第一次跑出来的报告足足有3000多行，把上游依赖、下游引用、每个函数的出入参全列了进去，结果AI在后续对话里大量遗漏信息——不是它不认真，是真的装不下了。
解决思路是分层投喂。SKILL.md里规定：默认只生成"一级概要报告"，包含模块地图和顶层依赖关系，控制在两三百行以内。只有当用户明确要求"深挖某个模块"时，才运行更细粒度的子分析脚本，聚焦单个模块展开。这样既保证了AI不会错过全局地图，又留足了上下文空间给它处理具体的代码修改任务。
另外报告本身的排版也有讲究。我在实践中发现，表格形式的依赖矩阵在AI眼里并不友好，它理解"自然语言+列表"的效率远高于"多维表格"。所以我的最终报告模板长这样：
## 模块地图 - orders：订单核心域，包括下单、改单、取消流程；依赖 payment、product - payment：支付域，对接微信、支付宝、内部钱包；被 orders 调用，不反向依赖 ## 风险标记 - inventory 模块存在循环依赖（inventory -> logistics -> inventory） - legacy_promo 模块无单测覆盖，且import中间件层，重构时需注意这种格式，AI读取时几乎不需要额外解析就能直接"理解"项目的结构。
5.3 触发失败：为什么AI不按Skill指令走
Skill文件放好了，description也写得够具体，但AI有时候还是会无视它，凭自由发挥回答。这种情况排查起来最让人头大，因为它不报错，只是"没按剧本走"。
我总结下来主要有三个原因：
第一，用户意图和Skill description之间的语义匹配度不够。比如用户说"这个系统怎么这么乱"，AI可能理解成普通的吐槽，而不是架构分析需求。解决方法是让Skill的description覆盖到更多口语化、模糊化的表达，比如把"系统怎么这么乱""跨模块改造""影响范围"都写进去。
第二，模型版本和上下文窗口的影响。某些较弱的模型在上下文拥挤时，技能索引可能被截断或降权。我的做法是尽量在会话开头就把架构问题抛出来，这时候上下文最干净，AI对技能索引的判断也最准确。
第三，指令冲突。如果项目根目录有AGENTS.md规定了"所有回答都必须先做X"，而Skill要求先做Y，AI可能陷入指令冲突，最后随机选了某一条执行。解决方法是打开调试模式看AI的"思考痕迹"，确认它有没有和Skill相关的决策。
5.4 Codex和Claude Code常见报错排查
使用这两个工具的过程中，我也积累了几个高频问题的排查经验。这里不是要展开讲某个古怪报错，而是分享一些通用排查思路。
Codex最常遇到的是认证和endpoint相关的报错。启动命令后如果提示连接失败或者endpoint错误，第一件事检查配置文件里的API地址有没有被改写，第二件事确认登录token是否过期。这类问题大多和本地配置污染有关，清理配置目录后重新登录基本能解决。
Claude Code这边，报错类型就更多样一些。比较常见的是启动闪退、对话中途断掉、第三方工具调用失败。我的通用排查顺序是：先看终端里的日志输出，再查~/.claude/目录下的日志文件，最后考虑重装。老实说，这类工具迭代速度极快，很多"诡异问题"其实都是版本升级引入的兼容性Bug，升级或者降级到稳定版本往往立竿见影。
还有一个经验很值钱：新版本发布之后不要立刻升级。我在这两个工具上吃过好几次亏——某个小版本引入了Skill加载机制的改动，我的现有配置直接失效。现在的习惯是锁定一个稳定版本，等社区反馈一两个星期再决定是否升级。在这个领域，"稳定压倒一切"不是一句空话。
5.5 本地模型调用与Skill的兼容性
最后聊一个很多人关心的话题：能不能让Claude Code或Codex接入本地模型，再配合Skill使用？这个方向确实有人在玩，理论上完全可行——CLI工具只是Agent框架，底层模型可以替换成本地部署的LLM。
但实测下来，效果差异很大。本地模型的能力如果达不到第一梯队水平，加载了Skill也可能"看不懂"或者"不执行"。Skill本质上是一份需要在模型推理中发挥作用的文本指令，模型的指令遵循能力越强，Skill的效果才越明显。用3B量级的本地模型跑复杂Skill，基本是浪费感情。
我的建议是：本地模型可以做测试和简单编码任务，但生产级项目的架构分析，还是要用好一点的在线模型。毕竟架构分析需要综合理解、多步推理，这不是小参数模型现阶段能胜任的。
6. 实操总结与下一步扩展建议
我在这套方案上实际跑了几周，最核心的体感是：Skill接入架构分析，就是给AI编程装了一个"项目认知预加载"机制。它不改变模型的推理能力，但改变了模型获得信息的质量和结构。同样一个AI，加载Skill前后对项目的理解完全像两个人。
几个亲测有效的经验再强调一遍：
第一，SKILL.md的description直接决定触发率，务必把可能的使用场景口语化、列举完整，宁可写成"废话大全"，也不要写得曲高和寡。
第二，架构报告要分层生成，全局概览和局部深挖分开，别指望一次把项目全部塞给AI。
第三，脚本输出必须严格结构化，AI对"编号+要点+路径"的文本理解力最好，别输出一大堆无组织的信息垃圾。
这套Birdview Skill后续还可以往几个方向扩展。比如接入Git历史分析，看看哪些模块最近改动频繁、哪块代码天生爱出Bug；比如生成架构变更提案，AI在动手之前先写出"我准备怎么改、影响哪些模块、回滚计划是什么"，经过确认再动工。这些玩法一旦跑通，AI在那个项目里就不再只是一个"写码工具"，而是有架构意识的协作者了。
如果你正在把Codex或Claude Code用在自己的核心项目上，我强烈建议你也去设计一套属于自己项目的"项目认知Skill"——不一定非得叫Birdview，但核心思想是一样的：让AI先看到森林，再让它动一棵树。
