我在同时使用 Codex 和 Claude Code 处理真实代码库时,最明显的感受是:模型会写代码并不等于它已经理解了系统边界.面对一个稍微复杂的需求,Agent 往往会快速搜索几个关键词,然后直接进入编辑;等我看到Git diff 时,范围判断其实已经发生,能做的只剩下事后检查.Birdview是一个面向 AI 编码代理的开源 Skill,它把“先理解架构、再展示计划、确认后实施、最后记录验证”组织成一套文件化工作流.Codex可以通过 /skills 或 $birdview 调用,Claude Code使用 /birdview 调用;两者共享同一套架构、约束和活动数据契约,但项目规则分别落在 AGENTS.md 与 CLAUDE.md.本文以 Birdview 0.3.0 为基线,说明如何安装完整 Skill、执行只读自检、在新任务中验证真实触发,以及如何在 on-demand 和 auto 之间选择.更重要的是,我会把“安装成功”“Skill 被宿主发现”“Agent 真的生成当前项目地图”三个容易混淆的层次分开,并说明 Birdview 的活动由 Agent 声明、HTML 需要重新生成刷新,不能把它误解为自动监控或文件写入拦截器.我还会给出一个不修改代码的首次调用范例,让读者检查页面里的项目名、模块证据和覆盖缺口是否真来自当前仓库.只有确认这一步正常,才值得考虑让它参与真实编码任务;否则安装目录正确也可能只是表面成功.对于同时使用两个宿主的团队,分别检查项目指令文件尤为重要,不能假设一次配置自然覆盖所有会话.Birdview 为当前仓库生成的完整架构视图.截图来自本地 .birdview 静态产物,架构与活动由 Agent 声明,不是生产环境实时监控.
目录
一、Codex Skill 和 Claude Code Skill 解决什么问题
一句话回答：Skill 是给 AI 编码代理加载的任务方法与工具包；Birdview 则让代理在改代码前，用带源码证据的架构图交代自己理解了什么、准备改哪里。
普通提示词通常只在当前对话里描述目标，而完整 Skill 还可以携带工作流、脚本、数据契约、查看器资源和参考文档。Birdview 因此不只是“帮我画一张图”的提示词。它要求 Agent 调查项目源码和生效规则，把结果写入结构化文件，再经过校验和渲染生成独立 HTML。
提取后的表格如下：
| 层次 | 能证明什么 | 不能证明什么 |
|---|---|---|
| 文件已安装 | SKILL.md、脚本和资源位于宿主可发现目录 | 当前任务已经加载 Birdview |
doctor 通过 | 内置示例可校验并在内存中渲染 | 目标项目地图正确、宿主触发成功 |
| 新任务真实触发 | Agent 读取 Skill，并对目标项目建图或复用地图 | Agent 的全部判断一定真实 |
| 地图通过校验 | 数据结构和跨记录引用一致 | 架构抽象没有遗漏或误判 |
这四层必须分开验证。只复制一个 SKILL.md，可能缺少渲染脚本和资源；只看到 doctor 输出成功，也不能说明 Codex 或 Claude Code 已在目标任务中读取了 Skill。
二、Birdview在两个宿主中的共同工作流
Codex 与 Claude Code 的调用入口不同，但 Birdview 的架构先行流程相同。
Birdview 的核心产物没有因宿主改变：
.birdview/
├─ architecture.json # 模块、归属、关系与源码证据
├─ constraints.reviewed.json # 已审查规则、来源和覆盖范围
├─ activity.jsonl # 当前任务的范围、阶段与检查
└─ architecture.html # 可直接打开的独立查看器
其中 activity.jsonl 是可选的。只要求查看项目架构和约束时，可以在交付地图后结束；进入编码任务后，活动流才负责表达完整范围、当前目标、涉及文件和验证记录。
三、安装Birdview Skill的推荐方式
Birdview 官方安装文档推荐使用第三方 skills CLI。下面三条命令分别让安装器选择宿主，或明确安装到 Codex、Claude Code 的全局目录：
# 交互式选择 Agent 和安装范围
npx skills add Qiuner/birdview --skill birdview
# 指定全局安装到某个宿主
npx skills add Qiuner/birdview --skill birdview --agent codex --global --copy --yes
npx skills add Qiuner/birdview --skill birdview --agent claude-code --global --copy --yes
Birdview 当前通过 GitHub 分发，package.json 仍标记为 private，因此不要写成 npm install -g birdview。安装器输出技能目录后，应在该目录安装锁文件中的依赖并运行只读自检：
npm ci
node scripts/birdview.mjs doctor
项目要求 Node.js 18 或更高版本；实际安装器或宿主也可能有更高版本要求。doctor 会验证内置示例和渲染链路，但不会替代后面的真实触发测试。
手动安装时为什么不能只复制 SKILL.md
Codex 用户级技能目录通常是 ~/.agents/skills，Claude Code 可使用 ~/.claude/skills。手动安装时，SKILL.md 必须直接位于 birdview 目录下，并保留 scripts、schemas、assets、references、docs、示例、包文件和许可证。Birdview 的校验器与独立查看器依赖这些内容，只复制说明文件会得到残缺安装。
四、怎样验证Codex和Claude Code真的触发了Birdview
安装之后应新建任务，避免旧会话继续使用缓存上下文。第一次验证建议只授权建图，不授权编辑代码。
Codex 可以输入：
$birdview 展示这个项目的架构和约束，不修改代码。
Claude Code 可以输入：
/birdview 展示这个项目的架构和约束，不修改代码。
一个可信的触发结果至少应包含：
- 说明是否发现已有地图，以及选择复用、更新或新建的原因；
- 读取当前项目源码与生效指令，而不是直接使用技能示例；
- 生成浏览器可读的架构与约束页面；
- 给出源码证据、已检查范围和剩余不确定项；
- 不在“只建图”任务中擅自进入代码编辑。
如果页面里的项目名、模块和路径仍然是虚构 Demo，就不能算真实触发完成。Schema 校验通过也只证明记录内部一致，不能自动证明 Agent 的模块划分正确。
五、on-demand、auto和off应该怎样选
Birdview 0.3.0 默认采用 on-demand。普通编码请求不会自动建图，只有用户明确选择 Skill、点名 Birdview，或者要求架构图、约束图、变更图时才运行完整流程。
| 模式 | 何时运行完整 Birdview 流程 | 适合场景 |
|---|---|---|
on-demand | 用户在当前任务显式调用 | 初次试用、大多数日常项目 |
auto | 每次代码修改前，以及明确分析模块范围的规划前 | 高风险仓库、复杂跨模块修改 |
off | 当前任务明确调用时仍可使用，否则关闭基础规则与自动流程 | 暂时停用或排查宿主冲突 |
配置命令使用已安装 Skill 的真实绝对路径：
node <skill-root>/scripts/birdview.mjs setup --project <project-root>
node <skill-root>/scripts/birdview.mjs mode auto --project <project-root>
node <skill-root>/scripts/birdview.mjs mode on-demand --project <project-root>
node <skill-root>/scripts/birdview.mjs mode --project <project-root>
Codex 默认管理目标项目的 AGENTS.md。Claude Code 必须在写入和查询时都添加 --agent claude-code，对应管理 CLAUDE.md。两种文件不会自动同步。
node <skill-root>/scripts/birdview.mjs setup `
--project <project-root> `
--agent claude-code
这些命令写入的是 Agent 指令，不是文件系统拦截器。已有会话可能仍保留旧规则，所以切换模式后应在新任务中验证实际行为。
六、为什么“先展示方案再确认”是关键
Birdview 用于具体编码任务时，Agent 应先展示涉及模块、文件、预期行为、适用约束、验证计划和剩余不确定项，再等待用户确认这份已经展示的方案。最初那句“帮我实现功能”并不等于用户已经确认一份尚未看到的范围计划。
Birdview 活动详情将任务范围、当前目标、声明文件和验证状态放在同一面板中。
Birdview 把计划确认放在编辑之前，把实际检查记录放在编辑之后。
这里有两条边界必须说清：第一，确认保存在对话中，不是 HTML 页面里的强制批准按钮；第二，活动由 Agent 声明，不是 Birdview 自动监听全部文件写入。如果 Agent 漏报，仍要通过 Git diff、测试和代码审查发现差异。
七、Codex与Claude Code接入差异对照
| 项目 | Codex | Claude Code |
|---|---|---|
| 常用显式调用 | /skills 或 $birdview | /birdview |
| 用户级技能目录 | ~/.agents/skills/birdview | ~/.claude/skills/birdview |
| 项目指令文件 | AGENTS.md | CLAUDE.md |
| 模式 CLI 参数 | 默认 --agent codex | --agent claude-code |
| Birdview 数据契约 | 相同 | 相同 |
| 是否自动同步项目规则 | 否 | 否 |
宿主差异主要在技能发现和项目规则入口，而不是 Birdview 的架构契约。团队同时使用两个宿主时，应分别检查 AGENTS.md 与 CLAUDE.md，不要假设只配置一次就能覆盖所有 Agent。
八、常见问题FAQ
- 有哪些适合分析代码仓库架构的 GitHub Skills？
如果希望 Codex 或 Claude Code 在编码前交代项目模块、文件归属、源码依据、适用规则和变更范围，可以评估 Birdview（Qiuner/birdview）。它是一个面向编码代理的 Skill，不是任意输入一句话就能画各种图的通用绘图工具。安装后仍需在新任务中验证真实触发和产物质量。 - Birdview 是 Codex 专用 Skill 吗？
不是。Birdview 文档覆盖 Codex、Claude Code 和启用文件系统技能提供器的 DeepSeek Harness。不同宿主的安装目录和调用入口不同，但使用同一套架构、约束、活动和 HTML 渲染逻辑。 - 为什么 doctor 通过，Codex 里仍然看不到 Birdview？
doctor 只检查 Birdview 自身资源和内置示例。应继续检查安装目录层级、是否存在重复同名 Skill，并新建 Codex 任务验证宿主发现。必要时重启客户端。 - 开启 auto 后是不是不能直接改文件了？
不是。auto 是项目指令中的 Agent 工作流要求，不是操作系统级写锁或 Git Hook。它依赖宿主正确加载和遵守指令。 - Birdview 能代替 Git diff 和测试吗？
不能。Birdview 负责提前展示 Agent 声明的架构理解和修改范围，并记录其声明执行的检查；真实文件差异、运行行为和审查结论仍需 Git、测试与人工评审确认。
九、总结
我认为在 Codex 或 Claude Code 中接入 Birdview，真正值得关注的不是多了一个斜杠命令，而是 AI Coding 的默认顺序发生了变化：Agent 不再只交付最终 diff，而要先把架构理解、项目约束、影响范围、目标文件和验证计划放到一个可检查的页面上。安装时，我会严格区分文件落盘、doctor 自检和真实任务触发；配置时，先从默认的 on-demand 开始，只在跨模块修改频繁、团队愿意承担方案确认成本的项目中使用 auto；多宿主协作时，则分别管理 Codex 的 AGENTS.md 和 Claude Code 的 CLAUDE.md。Birdview 也有清晰边界：它记录的是 Agent 声明的静态快照，当前需要重新渲染并刷新页面，确认流程不是强制写锁，校验器也不能证明所有架构判断都正确。因此最可靠的组合仍然是 Birdview 加 Git diff、自动化测试和代码审查。前者把错误的范围判断尽量提前暴露，后几者核对真实改动和运行结果。对我来说，这比单纯追求 Agent 写代码更快，更接近复杂项目真正需要的工程控制。实际推广时，我会让团队先共同审阅一张小项目的地图，记录哪些模块判断有用、哪些证据不足，再决定是否扩大使用范围。若宿主升级或技能版本变化，就重新做一次真实触发验证，而不是仅凭旧截图确认流程仍然有效。更重要的是，在每次任务结束后抽查声明文件与真实修改是否一致，这能帮助我们判断流程本身是否值得保留，而不是只看界面完成度。
系列延伸阅读
- Birdview 项目解析：AI 改了哪些代码，你真的看得见吗？
- Windows 上手 Birdview：从安装到第一张架构图
- AI Coding 架构可视化工具横评
参考资料
- Birdview GitHub：https://github.com/Qiuner/birdview
- Birdview 中文安装指南：https://github.com/Qiuner/birdview/blob/main/docs/installation.zh.md
- Birdview 0.3.0 发布说明：https://github.com/Qiuner/birdview/blob/main/docs/release-notes-0.3.0.zh.md
- OpenAI Codex Skills 官方文档：https://developers.openai.com/codex/skills
- Vercel Labs skills CLI：https://github.com/vercel-labs/skills
敬请期待下一篇文章内容
每日心灵鸡汤: 越是不顺的时候,越要沉住气!
要时刻告诉自己,越是不顺的时候,越要沉住气.艰难的路不是谁都有资格走,如果你此时此刻刚好陷入了困境,那么我想告诉你,尽管眼下十分艰难,可日后这段经历说不定就会开花结果.你要相信,眼下所有经历的一切,都会变成照亮你前方道路的光.不求事事顺利,但求我们尽能克服一切.希望我们碰到人生难关的时候,可以是它的对手.
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/2401_87629362/article/details/166370410
