两个技能让AI编程代理更懂你的代码库

如果你使用过编程 Agent CLI——OpenCode、Claude Code 或 Codex CLI——你可能已经注意到「能写代码的 LLM」与「动手之前先理解代码库的 Agent」之间的差距。这个仓库通过两个专注、经过实战检验的技能弥合了这条鸿沟。

一个 skill 是一组打包好的指令（一个 SKILL.md 加上可选的脚本和参考资料），用来教会你的 Agent 一个可重复的工作流。这套仓库提供了两个技能：

codebase-explorer 🔍 — 映射陌生仓库：入口点、模块职责、数据流，以及会让新手踩坑的陷阱。设计上只读不写。

software-engineering-workflow 🧱 — 把模糊的任务转化为深思熟虑的变更：发现需求、选择最简单安全的设计、实现，然后验证并移交。

🔍 codebase-explorer：编码之前先了解

当你指向一个仓库时，它首先读取顶层文档和本地 Agent 指令，然后用 rg --files（或 repomix 如果有）清点文件，接着追踪真实的执行路径——路由、服务、存储、输出。产出一份结构化报告：系统概述（一段话）、模块列表、数据流图，以及「陷阱」章节，列出令人意外的约定或配置陷阱。它随仓库规模而扩展：小项目得到完整的端到端导览；大项目只得到你询问的那些路径。它从不编辑文件或泄露密钥。

适用场景：加入新代码库、评估 bug 范围，或为 Agent 准备变更前置。

🧱 software-engineering-workflow：带着意图变更

这个技能强制执行一个轻量循环。编码之前，它先确立预期结果并检查相关代码、测试和约定——只向你询问它无法安全推断的内容。对于更大的代码库，它会建议先运行 codebase-explorer：

npx skills add https://github.com/mbuyco/skills --skill codebase-explorer

实现期间，它倾向于选择满足需求的最简单设计（KISS、YAGNI），通常先在一个文件中原型化核心逻辑，再扩散到其他文件。之后它运行最窄范围的有意义的检查——不只是 lint——并报告：变更了什么、关键决策、所做的假设，以及剩余风险。

适用场景：你希望 Agent 做规划和实现，而不是单纯的自动补全。

🤝 为什么它们配合默契

codebase-explorer 回答「这怎么工作的？」；software-engineering-workflow 回答「我们如何安全地变更它？」先运行 explorer 建立共享上下文，然后把这份上下文交给 workflow skill，让你的 Agent 带着理解去编辑，而不是靠猜测。

把这两个技能放到 skills/、.opencode/skills/ 或 ~/.config/opencode/skills/ 目录。通过名称调用——/skill codebase-explorer——或者让你的 harness 根据请求自动选择。

两者都与 OpenCode、Claude Code 和 Codex CLI 兼容。开始探索，然后开始构建。 🎯