1. 项目概述一个为AI编码伙伴量身定制的“开发工具箱”如果你和我一样日常开发已经离不开像 Cursor、Claude Code、GitHub Copilot 这样的 AI 编码助手那你肯定也遇到过类似的困扰有时候你希望 AI 能帮你完成一个相对复杂的任务比如“给项目添加一个用户登录功能”但直接把这个需求丢给它结果往往不尽人意。AI 可能会生成一堆零散的代码或者完全误解了你的架构意图最后你还得花大量时间去沟通、修正和整合。这正是我创建dev-kit这个项目的初衷。它不是一个庞大的框架也不是一个强制性的规范而是一个轻量级的“开发工具箱”。它的核心思想源于Spec-Driven Development规范驱动开发但做了一次关键的“瘦身”和“实用化”改造。简单来说dev-kit提供了一套标准化的“工作流技能”你可以像给工人配备扳手和螺丝刀一样把这些技能“安装”到你的 AI 编码助手我习惯称它们为“代码代理”或“vibe-coder”上。安装之后AI 就能按照我们预设的、更符合人类工程思维的方式去拆解任务、执行开发最终交付高质量、可集成的成果。想象一下你不再需要对着 AI 反复描述“先建这个文件再写那个函数注意这里要校验……”。你只需要说“用/dev-kit.ticket为‘用户登录功能’创建一个开发工单。” AI 就会自动生成一份结构清晰、包含验收标准的任务说明书。然后你说“用/dev-kit.work处理这个工单。” AI 就会按图索骥一步步实现功能。这大大提升了人机协作的效率和产出的确定性。dev-kit适合所有正在或准备将 AI 深度融入日常开发流程的开发者无论是独立开发者、小团队还是希望规范内部 AI 使用方式的技术负责人。2. 核心理念为什么“轻量级”的规范驱动开发更有效在深入工具细节之前有必要先聊聊背后的理念。我最初接触到像openspec和 GitHub 官方的spec-kit这类项目时确实被Spec-Driven Development的概念吸引了。它的理想很美好为 AI 编写极其详细、机器可读的规范文件告诉 AI 项目的方方面面——从代码风格、架构模式到部署流程。理论上这能让 AI 的输出极度可控和一致。但实际用下来我发现了一个悖论过于详尽的规范有时反而会束缚 AI 的创造力甚至导致其表现下降。这就像你教一个孩子画画如果你把每一步线条的角度、颜色的RGB值都规定死他可能画得“很标准”但失去了灵性和应对意外情况的能力。AI 也是如此当规范复杂到一定程度它可能会过度拟合这些指令忙于满足各种格式和约束而在解决核心问题的逻辑推理上分心。因此dev-kit采取了不同的策略“工作流”优先于“静态规范”。我们不追求用一份庞大的文档定义一切而是定义几个关键的、高价值的协作“节点”。每个节点即一个技能都是一个封装好的、目标明确的动作。比如init负责初始化项目环境ticket负责生成任务work负责执行任务。这样做的好处显而易见降低认知负担AI 不需要在每次交互时都去理解和应用一整套复杂的规范它只需要聚焦于当前技能所要求的上下文。提升灵活性你可以自由组合这些技能。今天用ticketwork开发新功能明天用refine优化文档后天用review做代码审查。技能之间松耦合适应不同的场景。结果导向每个技能都设计为产出明确的结果物如一个工单文件、一套代码变更、一份评审意见这使得整个协作过程可追踪、可验证。dev-kit的本质是为“人-AI”协作建立一种高效、低摩擦的协议而不是用铁律去限制AI。它承认并利用了当前大语言模型在遵循指令和上下文学习方面的优势同时规避了其在不擅长的、需要长期记忆和复杂规则推理方面的短板。3. 环境准备与技能安装全指南dev-kit的使用入口是npx skills这个命令行工具。它本身不依赖特定的 AI 编辑器理论上任何能执行 Node 命令并支持某种形式“技能”或“自定义指令”的 AI 编码环境都可以接入。下面我会详细拆解安装的每一步并解释其背后的考量。3.1 理解npx skills与技能管理npx是 Node.js 自带的包执行器它允许你直接运行 npm 注册表里的命令而无需先进行全局安装。skills在这里是一个虚构的命令名它代表了一个技能管理工具。在dev-kit的语境下你可以把它想象成一个“技能应用商店”的客户端。当你运行npx skills add tom555my/dev-kit时发生了以下几件事npx会临时下载并执行skills这个命令或其背后的脚本。该命令会连接到预设的源比如一个 Git 仓库或特定的服务定位到tom555my/dev-kit这个技能包。技能包被解析里面包含的各个技能如dev-kit.init,dev-kit.ticket等的定义文件通常是某种配置文件或提示词模板会被下载。根据你的安装选项项目级或全局这些技能文件会被放置到 AI 编码助手能够识别和加载的特定目录下。注意具体的技能加载机制取决于你使用的 AI 编码助手。例如在 Cursor 中技能可能体现为“自定义指令”在 Windsurf 或一些 CLI 工具中可能体现为可调用的命令模板。dev-kit提供的是一套标准化的技能定义需要你的 AI 环境具备相应的“技能运行时”来支持。在安装前请确认你的开发环境是否支持类似的技能/插件/自定义工作流功能。3.2 两种安装模式项目级 vs 全局安装时最重要的一个选择就是作用域。dev-kit提供了两种模式项目级安装默认npx skills add tom555my/dev-kit这条命令会在当前项目根目录下创建一个用于存放技能的隐藏目录例如.skills/或.cursor/rules/具体取决于实现。技能仅对当前项目生效。适用场景这是最推荐的方式尤其是团队协作时。每个项目可以根据自身技术栈React、Vue、Node.js等和规范拥有独一份的技能配置。例如一个前端项目可能对dev-kit.ticket技能进行定制要求工单必须包含组件设计稿链接而一个后端项目则可能要求工单必须包含 API 接口设计。项目级安装保证了技能与项目上下文的高度绑定。实操心得我习惯在项目初始化后立刻运行项目级安装。这样所有后续进入该项目的协作者包括AI都默认使用同一套协作语言极大减少了沟通成本。全局安装npx skills add tom555my/dev-kit -g-g参数代表 global。这条命令会将技能安装到用户的全局配置目录例如~/.config/skills/。安装后技能对所有项目都可用。适用场景适合个人开发者或者用于安装一些“通用型”技能。比如dev-kit.research研究技能可能不依赖具体项目在任何地方你都可能想让 AI 帮你快速调研一个技术概念。避坑指南谨慎使用全局安装。如果不同项目对同一个技能如dev-kit.work有不同要求全局技能可能会造成冲突或产生不符合项目预期的输出。我的原则是只有明确与项目上下文无关的“工具类”技能才进行全局安装。3.3 技能预览与按需安装在决定安装全部技能之前先看看包里有什么总没错。列出所有可用技能npx skills add tom555my/dev-kit --list执行这个命令后终端会打印出dev-kit包内包含的所有技能列表及其简短描述。这能帮助你快速了解这个工具箱的全貌判断哪些技能是你当前急需的。安装特定技能如果你只需要其中的一两个功能完全没必要安装整个包。npx skills add tom555my/dev-kit --skill dev-kit.init --skill dev-kit.ticket通过--skill参数可以指定一个或多个技能名进行安装。这非常灵活节省资源只下载需要的部分。避免干扰防止不用的技能出现在 AI 的指令列表中造成干扰。渐进式采用你可以先从最核心的ticket和work开始用起感觉顺手了再逐步引入refine、review等技能。提示技能之间可能存在依赖关系。例如dev-kit.work技能可能预设了会读取由dev-kit.ticket创建的工单文件。在单独安装时请阅读技能文档如果提供或在实际使用中观察其行为确保依赖的技能也已就位或通过其他方式满足了前置条件。4. 核心技能深度解析与实战应用安装完成后你的 AI 编码助手就获得了新的“超能力”。下面我将逐一拆解dev-kit提供的六个核心工作流技能结合假设的实战场景详细说明它们如何运作以及如何用好它们。4.1/dev-kit.init- 项目初始化脚手架这个技能用于为新项目或现有项目快速搭建符合dev-kit协作规范的初始环境。它做了什么当你对 AI 激活/dev-kit.init技能时AI 会引导你完成一个交互式初始化流程通常包括确认项目信息询问项目名称、类型Web应用、库、CLI工具等、主要技术栈。创建标准化目录结构例如生成docs/存放规范、tickets/存放工单、scripts/存放自动化脚本等目录。生成基础配置文件创建.gitignore、README.md模板以及可能对 AI 有指导意义的项目说明文件如.cursor/rules/dev-kit-context.md。初始化技能配置在项目内创建技能所需的本地配置文件确保后续技能能正确运行。实战示例初始化一个 React TypeScript 项目你在空目录 /projects/my-app 中使用 /dev-kit.init。 AI执行技能 正在初始化 dev-kit 环境... 项目名称默认my-app: [回车] 项目类型1) Web应用 2) 函数库 3) CLI工具... 请选择: 1 主要前端框架1) React 2) Vue 3) Svelte... 请选择: 1 是否使用 TypeScript? (y/n): y 初始化完成 已创建目录/tickets, /docs 已生成文件README.md, .gitignore, .cursor/rules/project-context.md 项目上下文文件已更新包含 ReactTS 最佳实践指引。现在这个项目就有了一个适合 AI 协作的“工作间”。.cursor/rules/project-context.md文件会告诉后续在这个项目中工作的 AI“这是一个 React TypeScript 项目我们的代码风格是这样的常用的工具库是那些……”为高质量输出奠定了基础。4.2/dev-kit.ticket- 智能工单生成器这是我认为最核心、价值最高的技能。它将模糊的人类需求转化为结构清晰、AI或人类开发者可直接执行的“工单”。工单的标准结构一个由该技能生成的工单通常包含以下部分标题简洁的任务概述。背景/目标为什么要做这个任务解决什么问题。验收标准清晰、可测试的完成条件列表例如“用户能通过邮箱和密码登录”、“登录失败显示具体错误信息”。这是最关键的部分它定义了“完成”的边界。实现建议可能的技术方案、需要修改的文件、需要注意的依赖等。这部分为 AI 提供了上下文但不是强制命令。相关资源设计稿链接、API文档、参考代码等。如何高效使用它不要只说“创建一个登录功能的工单”。要提供丰富的上下文。你使用 /dev-kit.ticket我们需要一个用户登录功能。背景当前项目是一个电商网站已有用户表字段id, email, hashed_password, name。前端是 Next.js 14 (App Router)使用 next-auth 进行认证。验收标准1. 提供邮箱/密码登录表单页 (/login)。2. 集成 next-auth Credentials Provider。3. 登录成功跳转至 /dashboard失败显示错误。4. 添加简单的表单验证。相关文件lib/auth.ts 是现有的 next-auth 配置。 AI执行技能 正在生成工单... 工单已保存至/tickets/20240415_user_login.md打开这个.md文件你会看到一个结构完美、信息充足的任务说明书。接下来无论是你自己、队友还是 AI都可以基于这份工单开始工作极大减少了歧义和返工。注意事项验收标准的撰写质量直接决定后续开发效率。尽量使用“当...时应该...”的句式使其可验证。避免使用“优化性能”、“改善用户体验”这类模糊表述而是改为“将页面首次加载时间减少至2秒内”、“在表单提交时提供明确的成功/失败视觉反馈”。4.3/dev-kit.work- 基于工单的自动化开发这是“执行”环节的技能。它让 AI 读取指定的工单文件并开始逐项完成验收标准。工作流程定位工单你需要告诉 AI 工单文件的路径或者如果项目内只有一个活跃工单它可能会自动定位。分析任务AI 会仔细阅读工单理解背景、验收标准和实现建议。制定计划AI 会在内部或向你展示一个初步的实施计划先改哪个文件再处理哪个逻辑。迭代执行AI 开始编写代码。它会一边写一边对照验收标准并可能向你确认一些细节比如“登录成功后的跳转逻辑是使用router.push还是redirect”。生成变更最终AI 会提交一套完整的代码变更并可能附带一个简短的总结说明它完成了哪些验收标准。与直接对话开发的区别如果没有dev-kit.work你可能会这样和 AI 协作“现在实现登录功能。先创建app/login/page.tsx表单要有邮箱和密码字段...” 你需要扮演项目经理兼技术领航员。 而有了dev-kit.work你只需要说“处理工单/tickets/20240415_user_login.md。” AI 会自动切换到“执行者”模式以工单为唯一依据进行开发。你的角色变成了“验收者”只需在关键决策点提供输入大大解放了心智负担。4.4/dev-kit.refine- 文档与代码的“抛光”工具AI 生成的文档如注释、README或某些代码如复杂配置有时会存在啰嗦、不准确或格式不一致的问题。/dev-kit.refine技能就是用来解决这个问题的。应用场景优化 AI 生成的注释让注释更简洁、专业符合项目规范。重构复杂的配置对象使配置更清晰、易于理解。润色项目文档提升文档的可读性和专业性。统一代码风格对某段代码进行风格上的微调使其与项目其他部分一致。使用示例你AI 刚才生成了一段关于数据库连接的配置注释有点冗长。使用 /dev-kit.refine 优化它。 AI聚焦于你选中的代码块 原注释 // This is the configuration for connecting to the PostgreSQL database. We use environment variables for security. The host is from DB_HOST, port from DB_PORT... 优化后 // PostgreSQL 数据库连接配置参数从环境变量读取以确保安全。这个技能相当于一个专注的“文字编辑”它不改变功能逻辑只提升表达质量。4.5/dev-kit.review- AI 辅助代码审查代码审查是保证质量的关键环节。/dev-kit.review技能可以让 AI 扮演第一轮审查者的角色。审查维度当你对一段代码或一个 Pull Request 使用该技能时AI 通常会从以下几个角度进行分析功能性代码是否实现了预期功能是否存在逻辑错误或边界情况未处理代码质量是否符合项目的编码规范命名、格式是否有重复代码可以重构安全性是否存在潜在的安全风险如 SQL 注入、XSS性能是否有明显的性能瓶颈如循环内重复计算、不必要的渲染可维护性代码是否清晰易懂注释是否充分输出形式AI 会生成一份结构化的审查报告列出发现的问题按严重程度分级、具体的代码位置以及修改建议。它甚至可以直接提供修改后的代码片段。你对文件 utils/dataFetcher.ts 中的 fetchUserData 函数使用 /dev-kit.review。 AI执行技能 ## 代码审查报告fetchUserData 函数 **1. 高优先级问题** - **错误处理不完整** (第15行): try-catch 仅捕获了 fetch 错误未处理 JSON 解析错误或网络超时。建议使用更健壮的错误处理库或添加特定 catch 块。 - **潜在内存泄漏** (第22行): 在组件卸载时未清理可能的异步操作或事件监听器如果此函数在 React 组件中使用。 **2. 改进建议** - **可读性** (第10行): 魔法数字 5000超时时间应定义为常量 const API_TIMEOUT 5000。 - **类型安全** (返回类型): 函数返回 Promiseany建议明确定义为 PromiseUserData。 **建议修改代码示例** typescript // ... 修改后的代码片段 这能帮助开发者在提交 PR 前就发现并修复许多常见问题减轻人类审查者的负担。4.6/dev-kit.research- 快速技术调研员当你需要快速了解一个新技术、库或概念时这个技能能派上大用场。它能做什么你提供一个调研主题例如“比较 Next.js 14 中 Server Actions 与传统 API Routes 的优劣”AI 会基于其知识库截止到其训练数据日期生成一份结构化的调研摘要。内容通常包括概述、核心概念、优缺点对比、适用场景、简单的代码示例、相关资源链接。它会尽量以客观、对比的方式呈现信息帮助你快速决策。局限性说明需要注意的是AI 的调研基于其训练数据可能不是最新的。对于非常前沿或快速变化的技术其信息可能过时。因此/dev-kit.research的最佳用途是快速入门对一个陌生领域建立初步认知。方案对比在几个已知选项中快速梳理其特点。灵感启发了解某项技术的常见应用模式和最佳实践。 对于需要绝对准确和最新的信息它应该作为起点而不是终点最终仍需查阅官方文档或权威社区。5. 实战工作流串联从想法到上线的完整案例理论说再多不如看一个完整的例子。假设我们要为一个博客系统添加“文章点赞”功能。第一步初始化与规划我们在博客项目根目录已经通过/dev-kit.init初始化了环境。我们使用/dev-kit.ticket创建工单。你“使用/dev-kit.ticket。功能文章点赞。背景当前博客有Post模型id, title, content。需要新增点赞功能记录用户对文章的点赞防止重复点赞。前端需在文章详情页显示点赞按钮和计数。技术栈Next.js (App Router), Prisma, SQLite。”AI生成工单tickets/20240416_post_like.md包含详细的验收标准如“创建Like数据模型关联 User 和 Post”、“实现 API 端点POST /api/posts/[id]/like”、“前端按钮点击后发送请求并更新计数”等。第二步开发与实现我们使用/dev-kit.work处理该工单。你“处理工单tickets/20240416_post_like.md。”AI首先分析工单制定计划1. 扩展 Prisma Schema2. 创建数据库迁移3. 实现 API 路由4. 更新前端组件。然后开始执行。它创建prisma/schema.prisma中的Like模型生成迁移文件编写app/api/posts/[id]/like/route.ts最后修改app/posts/[id]/page.tsx和对应的客户端组件。过程中它会询问关键决策“点赞状态是实时查询还是前端乐观更新我建议乐观更新以提升体验。” 你回答“采用乐观更新。”完成所有变更后AI 提交代码并总结“已完成1. 数据模型与迁移2. 点赞/取消点赞 API3. 前端点赞按钮组件支持乐观更新。所有验收标准已满足。”第三步审查与优化我们使用/dev-kit.review对 AI 生成的 API 路由代码进行审查。AI可能指出“在route.ts中用户认证依赖getServerSession建议将认证逻辑提取为共享工具函数以提高可复用性。” 并提供修改建议。我们根据审查意见进行修改可以手动改也可以让 AI 根据建议再改一次。我们使用/dev-kit.refine优化 AI 生成的代码注释和组件内的 JSX 结构使其更清晰。第四步知识沉淀可选如果这是一个值得记录的技术方案我们可以使用/dev-kit.research。你“用/dev-kit.research调研一下‘在 Next.js 应用中实现点赞功能的最佳实践’特别是关于实时更新、防刷和数据结构设计方面。”AI生成一份简短的调研笔记我们可以将其补充到项目的docs/like-feature.md中供未来参考。通过这一套流程一个功能从想法到可测试的代码变得高度结构化、自动化且质量可控。你作为开发者始终处于“决策者”和“验收者”的高层角色而将重复性、规范性的执行工作委托给了 AI。6. 常见问题、排查技巧与进阶玩法在实际使用中你可能会遇到一些问题。下面是我总结的一些常见情况及解决方法。6.1 技能执行失败或未被识别问题输入/dev-kit.xxx后AI 没有反应或回复“未知命令”。排查步骤确认安装首先运行npx skills list或类似命令查看已安装的技能列表确认dev-kit技能是否存在。检查路径如果是项目级安装确保你当前终端所在目录是项目根目录。AI 代理通常只加载当前工作目录下的技能。环境兼容性确认你的 AI 编码环境Cursor, Windsurf, 某 CLI 工具是否支持通过npx skills安装的技能格式。dev-kit可能主要针对特定环境优化。查阅dev-kit项目的 README看是否有明确的环境要求。重启 AI 代理有时 AI 代理需要重启或重新加载才能识别新安装的技能。尝试重启你的编辑器或 AI 代理服务。6.2 生成的工单或代码质量不高问题/dev-kit.ticket创建的工单太笼统或者/dev-kit.work生成的代码不符合预期。提升技巧提供更丰富的上下文在创建工单时把你想到的所有细节都告诉 AI。包括技术栈的版本号、现有的相关代码文件、UI 库名称、甚至设计系统的约束。上下文越丰富输出越精准。迭代优化不要指望一次成功。如果生成的工单不好可以直接告诉 AI“这个工单的验收标准不够具体请补充关于错误处理边界和移动端适配的细节。” AI 会基于你的反馈进行修改。同样对于代码可以指出问题让其重写。利用项目上下文确保你的项目通过/dev-kit.init或手动方式拥有一个良好的.cursor/rules或类似的项目上下文文件。这个文件是 AI 理解你项目专属规范的“圣经”能从根本上提升代码的契合度。6.3 如何定制属于自己的技能dev-kit提供的技能是通用模板。真正的威力在于定制。基础定制直接修改安装在本地的技能文件。找到技能安装目录通常在项目内的.skills或全局配置目录你可以编辑技能的提示词模板。例如让dev-kit.ticket为你公司的项目固定添加“需关联 JIRA 任务号”的字段。创建新技能如果你发现某个工作模式反复出现可以考虑将其封装成新技能。研究现有技能的文件格式可能是.json,.yaml或.md文件模仿其结构创建一个新的技能文件然后通过npx skills add ./path/to/your-custom-skill进行安装。例如你可以创建一个deploy-to-staging技能自动执行构建、测试、部署到预发环境的系列命令。6.4 与团队工作流的整合版本控制技能配置将项目级的.skills目录或存放技能配置的目录纳入 Git 版本控制。这样团队所有成员拉取代码后就自动拥有了一致的 AI 协作环境。在 CI/CD 中融入 AI 审查虽然目前直接在 CI 中运行 AI 审查成本较高但可以将/dev-kit.review的输出作为代码提交前的一道本地检查关卡。可以编写一个简单的 Git 钩子pre-commit hook在提交前对变更的文件自动运行 AI 审查需调用 AI API并将报告输出给开发者参考。建立团队技能库团队可以维护一个内部的技能仓库存放针对公司技术栈如内部 UI 组件库、微服务架构定制的技能。新成员 onboarding 时一键安装就能快速让 AI 适应公司内部的开发规范。dev-kit代表的不仅是一套工具更是一种面向未来的、人机协同的软件开发范式。它不试图用 AI 取代开发者而是致力于让开发者能更高效地指挥和赋能 AI将创造力聚焦在真正需要人类智慧的设计、架构和决策环节。从今天开始尝试用/dev-kit.ticket来规划你的下一个功能你可能会惊喜地发现你和你的 AI 伙伴之间的对话从未如此顺畅和富有成效。