ai-agent-skills

给 AI 编程工具装上"导航仪"：Wednesday Agent Skills 如何让 AI 不再迷路

痛点：AI 编程助手在大型代码库里"睁眼瞎"

想象一下：你刚接手一个有 2000 个文件的老项目，让 AI 助手（Claude Code、Cursor、GitHub Copilot）回答"如果我改了 auth.ts 这个文件，哪些模块会受影响？"

没有上下文的 AI 助手会老老实实地去读文件——读 30 个、50 个、甚至 100 个文件，消耗海量 tokens，最后还给出一个可能"幻觉"出来的答案：某个完全无关的模块被它"想当然"地列为受影响方。这不是 AI 不够聪明，而是它根本没有项目的结构地图。

这就是 Wednesday Solutions 公司在日常开发中真实遇到的痛点。他们是做产品工程的公司，开发团队日复一日地与大型代码库打交道，AI 编程助手越来越多地介入工作流，但 AI "不认路"的问题始终无法绕过。

核心思路：预计算，不重读

Wednesday Agent Skills 的设计哲学很简单——提前把地图画好，AI 用时直接查。

具体做法是：在项目目录下运行一次 wednesday-skills map，系统会用 AST（抽象语法树）解析引擎遍历整个代码库，把每个文件的导入、导出、函数调用关系全部提取出来，存进一个 SQLite 数据库（graph.db）。

此后，无论 AI 问"这个函数被哪些地方调用了"还是"这个改动会影响谁"，系统直接在 SQLite 里毫秒级查询，消耗 tokens 接近零。根据官方数据，这种方式可以将结构类问题的 LLM token 消耗降低 70~90%。

系统架构：五层结构

整个系统分为五层，从上到下：

第一层：Agent 集成层。 系统与 Claude Code、Gemini CLI、Cursor 等主流 AI 编程工具深度集成。通过读取项目根目录下的 CLAUDE.md、GEMINI.md、.cursorrules 等配置文件，AI 工具能自动识别项目中有哪些技能可用。

第二层：技能注册层（.wednesday/skills/）。 这里存放的是具体任务的行为规范，包括：

• codebase-intel：代码库结构问答
• brownfield：遗留代码分析与改进
• greenfield：新项目并行规划（PM + 架构师 + 安全三方同时运行）
• pr-review：PR 评论修复引擎
• deploy-checklist：部署检查清单
• wednesday-git：统一 Git 工作流

第三层：智能引擎（src/brownfield/）。 这是核心计算层，包含：

• 适配器系统（adapters/）：支持 11 种编程语言的 AST 解析（JS/TS/Python/Go/Swift 等），每种语言返回 {imports, exports, gaps, meta} 标准化结构
• 图构建引擎（graph.js）：协调适配器结果，构建有向依赖图
• 存储层（store.js）：SQLite 封装（better-sqlite3），表结构为 nodes/edges/symbols
• 增量缓存（cache.js）：基于 SHA1 哈希，只重解析有变化的文件

第四层：分析工具。 构建好依赖图之后，系统提供两个杀手级命令：

• wednesday-skills blast <file>：计算变更的"冲击半径"——不仅列出直接依赖方，还包括间接的传递依赖
• wednesday-skills score <file>：计算文件风险评分（0-100），综合考虑导入量、公共接口数量、测试覆盖率和历史 bug 记录

第五层：哨兵机制。 通过 Git hooks 自动维护依赖图的时效性：

• pre-commit：确保新文件带有 @wednesday-skills:purpose 头部注释
• post-commit/post-merge：增量更新 graph.db，保证 AI 查询时数据是最新的（< 1 秒完成）
• commit-msg：通过 commitlint 强制执行 conventional commit 格式

质量门禁：AI 写代码也有"交警"

系统还内置了代码质量护栏：

• 圈复杂度限制：提交前自动检查，函数的圈复杂度不得超过 8，超标则阻止提交
• 设计资产管控：限制 AI 随意引入新的 UI 组件，要求只能从 shadcn、Magic UI 等已批准的组件库中选择
• Terminal Dashboard（wednesday-skills dashboard）：一个基于 React + Ink（终端 UI 框架）的实时面板，展示 PR 状态、覆盖率、Sonar 扫描结果，支持 30 秒自动刷新

上手体验：安装只需一行命令

npx @wednesday-solutions-eng/ai-agent-skills install

或通过 Bash 脚本：

bash <(curl -sL https://raw.githubusercontent.com/wednesday-solutions/ai-agent-skills/main/install.sh)

安装后，系统会初始化 .wednesday/ 目录（包含依赖图、技能配置、缓存等），并自动注册 Git hooks。无需 Docker，无需 GPU，Node.js >= 18 即可运行。

局限与争议

技术评估需要客观。以下几点值得注意：

1. 依赖图维护成本。 每次 Git 操作都要触发 post-commit 更新 graph.db，在大型 monorepo 中可能带来轻微性能开销。

2. 适配器质量差异。 不同编程语言的 AST 解析器质量参差不齐，TypeScript/JavaScript 的适配器最成熟，而小众语言的适配器可能遗漏复杂的动态导入模式。

3. 非 AI 推理类问题无帮助。 系统只对"结构类"问题（依赖、调用链、变更影响）有效，对于需要真正语义理解的复杂业务逻辑问题，仍然需要 AI 直接阅读代码。

4. SQLite 存储限制。 graph.db 是本地文件，多人协作场景下需要手动同步，且不支持分布式访问。

行业意义：重新定义"代码上下文"

Wednesday Agent Skills 代表的趋势是将"代码理解"这件事从 LLM 推理转移到确定性计算。这不是在削弱 AI 的能力，而是在更聪明地分配计算资源——让 AI 只做真正需要理解的事，把记忆和检索交给数据库。

这种"预计算 + 精确召回"的架构思路，与 RAG（检索增强生成）有异曲同工之妙，但更聚焦于代码结构这一垂直领域。随着 AI 编程工具的普及，这类"代码库导航基础设施"的需求会持续增长。