AI编程进阶：用Skill给Codex和Claude Code装架构全局视角

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遇到帮我把这个报错处理一下这样的需求时它会按照通用经验回答大概率是搜一下异常类型、看一下堆栈、改一下代码。但如果你的项目里有一套统一错误码规范、有一个集中式异常上报系统、甚至要求所有对外接口返回统一格式通用模型根本不知道这些。而你要是写了一个错误处理SkillAI就会被引导着先去查错误码表再定位到对应的错误处理模块最后按规范生成代码。Skill这个东西现在各家平台都有类似的实现。Claude Code在较新的版本中开始支持~/.claude/skills/目录下的自定义Skill通过SKILL.md文件声明Codex也在逐步跟进支持通过配置文件或指令加载类似的技能包。核心机制大同小异都是渐进式披露平时不占用上下文需要时AI主动读取对应技能文件按里面的步骤执行。2.2 Skill、Prompt和MCP三者到底什么关系很多刚接触的朋友会把Skill和Prompt搞混。简单区分一下Prompt是一次性的对话指令用完即弃没有沉淀价值。你每次换新会话都得重新把所有背景、要求讲一遍。Skill是可复用的、结构化的方法论文档存放在固定路径AI可以根据任务自动决定是否加载。它是有记忆的。MCPModel 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项目模块地图生成器的一个demoimport 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, encodingutf-8, errorsignore) 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返回的数据是结构化schemaAI读起来反而没有一份精心排版过的markdown报告来得直观。模型对文本的理解能力比对JSON强得多这一点在实测中差异很明显。第三脚本方案的可移植性太好了。整个Skill目录直接拷到另一台机器、另一个项目改一下根路径配置就能跑不依赖任何环境变量或服务注册。当然MCP也有它的场景如果你需要让AI实时查询Git历史、动态监控测试覆盖率、对接内部工具链MCP是更合适的选择。一句话总结静态分析交给Skill脚本动态交互交给MCP两者配合反而最舒服。4. 从零到一把Birdview接入Codex和Claude Code4.1 前置准备Codex CLI和Claude Code的安装在开始接入之前先确保本地环境里有Codex CLI和Claude Code命令行工具。Codex CLI当前主要通过npm安装或者Homebrew安装。国内使用时不涉及任何网络代理问题只需要确保登录认证通过、账号有可用额度。Claude Code也是类似的命令行工具安装后运行claude命令进入交互式终端。这里有一个小建议两个工具的认证信息务必分开管理。我遇到的最常见问题就是多个账号在同一台机器上导致工具读取了错误的token表现就是登录无效或者额度异常。解决办法是把配置目录隔离好Codex的认证信息在~/.codex/auth.jsonClaude Code的在~/.claude/下不要混淆。4.2 将Birdview Skill装入Claude CodeClaude 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要求先做YAI可能陷入指令冲突最后随机选了某一条执行。解决方法是打开调试模式看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先看到森林再让它动一棵树。