铺垫了一个季度，终于可以深入探讨 AI 时代 Harness 工程在后台管理系统中的具体实践了。本次分享的核心，是让 AI Agent 真正理解你的项目，从而输出更可靠、更贴合业务逻辑的代码。
先交代背景：如今 AI Coding 的覆盖率已接近 100%，但实际使用中，AI 在面对特定项目时输出的代码往往不尽如人意，根本原因在于它不够“懂”你的项目。为了解决这一痛点，开源项目 V3 Admin Vite 在原有 Rules 基础上，新增了项目级约定与 Skills，目标是让 AI 的输出更加稳健可靠。
背景
程序员群体中 AI Coding 的普及率已逼近 100%，尽管 AI 能力持续增强，但让它针对具体项目编码时，仍频繁出现输出代码质量不达标的情况。
为减少此类问题，V3 Admin Vite 开源项目在现有 Rules 之上，引入了项目级约定与 Skills，以此保障 AI 输出更加精准、可依赖。
目标
完成项目级约定与 Skills 的内置，使 AI Agent 充分理解我们的项目结构与规范，从而输出理想、高质量的代码。
前置知识
动手之前，有必要先厘清三个概念：CLAUDE.md、Rules 与 Skills。它们的作用范围、加载方式及适用场景差异显著，通过下表可以更直观地理解：
| 方面 | CLAUDE.md | Rules | Skill |
|---|---|---|---|
| 加载方式 | 每次会话自动加载 | 每次会话，或打开匹配文件时自动加载 | 按需调用，当相关任务触发时加载 |
| 作用范围 | 整个项目全局 | 可限定在特定文件路径范围内 | 面向特定任务或场景 |
| 最佳用途 | 核心约定、构建命令、全局规则 | 特定语言或目录的专有指南 | 参考材料、可重复执行的工作流程 |
| 何时使用 | 项目通用约定、“始终执行 X” 类规则 | / | 可重用内容、技术参考文档、重复性任务 |
| 示例 | 使用 pnpm 而非 npm；提交前运行测试 | / | /deploy 执行部署检查清单；熟悉 API 文档与端点模式 |
总结
- 对于每个会话都需要生效的说明，使用 CLAUDE.md ： 构建命令、测试约定、项目架构等核心内容
- 使用 Rules 保持 CLAUDE.md 精简聚焦： 带有 paths frontmatter 的 Rules 仅在 Claude 处理匹配文件时加载，有效节约上下文
- 对于 Claude 有时才需要的内容，使用 Skills ： 例如 API 完整文档或通过
/触发的部署清单 - CLAUDE.md + Skills 组合： CLAUDE.md 存放始终开启的规则，Skills 存放按需加载的参考材料。比如 CLAUDE.md 中写 “遵循我们的 API 约定”，Skill 中则包含完整的 API 风格指南
通俗解释
- CLAUDE.md： 每次会话都生效的通用约定
- Rules： 每次会话但仅局部生效的规则
- Skills： 按需调用且场景固定的执行步骤
本期实现
新增项目级约定
为了让 AI 真正理解项目架构并遵守约定，我们在项目根目录新增了 AGENTS.md 与 CLAUDE.md 两个配置文件。内容涵盖三大模块：命令、架构、约定，总行数控制在 200 行以内。从实践效果看，基于开源项目 andrej-karpathy-skills 来完善这三个模块是一个高效的选择——该项目通过简单的四条原则，就能有效约束 AI 输出，避开常见陷阱，效果十分显著。
需要特别说明的是：CLAUDE.md 主要面向 Claude Code 工具，而 AGENTS.md 则覆盖 Cursor、Antigravity、Trae、CodeX 等更广泛的 AI 编码工具。因此我们优先输出通用性更强的 AGENTS.md 文件，再通过关联机制让 CLAUDE.md 共享同一份内容，避免重复维护。
新增项目 Skills
编写 Skill 时，官方提供的 skill-creator 工具能大幅提升效率，远比自己从零开始编写快捷。如果需要深入学习 Skill 的编写技巧，可以查阅相关官方文档。
实践中，我们将编写好的 Skill 存放在通用的 .agents/skills/ 目录下，然后使用软链接命令 ln -s 与 .claude/skills/ 关联，这样同样避免了重复维护两份文件。
针对 V3 Admin Vite，首批新增了以下项目专用 Skill（每个 Skill 内容严格控制在 500 行以内）：
v3-create-crud：创建增删改查页面v3-upsert-store：创建或更新全局状态v3-upsert-route：创建或更新路由表v3-use-utils：内置工具的使用教程v3-use-composables：内置组合式函数的使用教程
将这些后台管理系统中高频出现的需求抽象成 Skill 之后，AI Agent 确实能更准确地理解意图、生成代码，效果立竿见影。
安装社区 Skills
除了项目自建的 Skill，我们还引入了社区中与 Vue 项目高度兼容的第三方 Skill，包括但不限于：
piniapnpmunocssvitevitestvuevue-best-practicesvue-router-best-practicesvue-testing-best-practices
这些主要来自 antfu/skills 仓库。它们以 skills-lock.json 文件的形式记录，默认不包含在项目中。如果需要，可以运行 npx skills experimental_install 命令安装到本地，安装后会在 .agents/skills/ 目录下出现。
实践总结
至此，我们阶段性实现了标题中所说的 AI 时代 Harness 工程在后台管理系统中的实践。
基于这套方案并配合软链接方式，目前已支持 Claude Code、CodeX、Cursor、Trae、Antigravity 等主流 AI Coding 工具。当然，AI Agent 的发展速度极快，未来一定还会涌现更多不同的实践方案，值得我们持续关注和跟进。
