1. 项目概述：dotAI，一个为Claude Code深度定制的AI开发工具箱

如果你和我一样，日常重度依赖Claude Code进行开发，那你肯定也经历过这样的时刻：想让它帮忙调试一个复杂错误，结果它给出的建议隔靴搔痒；想让它遵循TDD流程写个测试，结果它直接跳过了“红”的阶段；或者，当你想让它深入理解某个第三方库的源码时，它只能给出基于文档的猜测。这些痛点，正是 udecode/dotai 这个项目诞生的背景。它不是另一个普通的代码生成插件，而是一个旨在将Claude Code从一个“聪明的代码补全工具”升级为“具备系统化工程思维和深度探索能力的AI结对编程伙伴”的工具箱。

简单来说，dotAI通过一系列精心设计的插件、命令和技能，为Claude Code注入了结构化的开发方法论和强大的上下文获取能力。它把调试、测试、源码研究这些原本松散、依赖提示词技巧的任务，变成了可预测、可重复的标准化流程。核心价值在于，它让AI在编码过程中的行为更可控、更深入、更符合资深工程师的思维习惯。无论是独立开发者想提升AI辅助的效率，还是团队希望统一AI协作的规范，dotAI都提供了一个极具参考价值的实践框架。

2. 核心架构与设计哲学解析

2.1 模块化设计：插件、命令与技能的三层体系

dotAI的架构清晰地区分了三种不同粒度的能力单元，这种设计让整个系统既灵活又强大。

插件 是能力的载体。比如 debug 插件封装了一套四阶段调试框架， test 插件内置了完整的TDD工作流。每个插件都是一个独立的功能包，可以被单独安装、更新或禁用。这种设计的好处是显而易见的：你可以按需组合。如果你今天只做前端UI，可能只需要 frontend-design 插件；如果你在啃一个棘手的后端Bug，那么启用 debug 和 dig 插件就是最佳选择。这种“乐高积木”式的架构，避免了功能臃肿，让Claude Code能始终保持轻量、专注的状态。

命令 是主动触发的入口。它们通常以 / 开头，比如 /dotai:create-tech-stack 。命令是用户与插件功能进行明确、一次性交互的桥梁。当你需要生成一份技术栈文档时，你不会希望AI在聊天过程中突然开始写文档，而是明确地发出指令。命令确保了意图的清晰和边界的明确，防止AI在常规对话中“越界”执行复杂操作，干扰当前的思维流。

技能 是上下文触发的自动化能力。这是dotAI设计中最精妙的部分。技能不需要你显式调用，AI会根据当前对话的上下文自动判断是否需要激活某个技能。例如，当你描述一个Bug现象时， debug 技能可能会被自动触发，引导AI进入结构化的调试流程；当你在讨论一个尚未实现的函数时， tdd 技能可能会介入，建议你先写一个失败的测试。这模拟了资深工程师在思考时，脑海中自动调用的各种“思维模式”和“检查清单”，极大地提升了AI交互的流畅度和智能感。

2.2 动态提示词系统：将工程规范“编译”进AI的思考过程

.claude/prompt.yml 这个文件是dotAI的灵魂所在。它不是一个静态的“系统提示词”，而是一个动态的钩子注入系统。传统的长提示词容易被AI忽略或遗忘在上下文深处，而dotAI的提示词系统在AI生成响应的关键节点进行“注射”，确保关键步骤不被跳过。

beforeStart 钩子在Claude准备开始组织回答前运行。比如里面配置的 SKILL-ANALYSIS ，会强制AI在动笔前先扫描一遍可用的技能，并调用其中适用的。这就好比你在动手编码前，总会先想想“这个问题适合用TDD吗？需要先深入源码看看吗？”，把这种元认知能力赋予了AI。

beforeComplete 钩子在AI声称完成任务、准备结束回答前运行。这里配置的 VERIFICATION 检查项（如类型检查、代码格式化）是质量的最后一道关卡。它防止AI提交一份看起来完整但无法通过基础质量门禁的代码，强制其进行自检。这就像资深工程师在提交代码前，总会本能地跑一遍测试和lint。

afterCompact 钩子则用于在Claude的上下文因过长而被压缩后，重新恢复一些关键的上下文信息。这个设计考虑到了长会话场景，确保了核心的工作记忆不会丢失。

这套系统本质上是在Claude Code的推理链上设置了几个“检查点”，将软件工程的最佳实践（如代码审查清单、开发流程）固化到了AI的协作流程中，使其输出更具一致性和可靠性。

3. 核心插件深度解析与实操指南

3.1 debug 插件：四阶段结构化调试框架

盲目地让AI“看看这个错误”通常效率低下。 debug 插件提供的四阶段框架，将调试从一个模糊的请求变成了一个可追踪的科学研究过程。

第一阶段：问题表征与复现 。AI不会直接跳进代码，而是首先引导你清晰、无歧义地描述问题：在什么环境下、执行什么操作、输入是什么、期望输出是什么、实际得到了什么。它会要求提供完整的错误堆栈截图或文本。这个阶段的目标是建立一个可靠的、可重复的“实验”环境。我的经验是，花时间在这一步磨清楚问题描述，往往能自己发现问题的根源，或者至少为AI提供了无噪声的起点。

第二阶段：假设生成与优先级排序 。基于第一阶段的信息，AI会运用其知识库，生成多个可能的原因假设。关键在于，它不会只给一个最可能的猜测，而是会列出多个，并根据可能性、验证成本进行排序。例如，对于“网络请求失败”，假设列表可能是：1. 本地代理配置问题（易验证）；2. API端点地址错误（易验证）；3. 服务器端CORS策略问题（中等验证成本）；4. 客户端证书问题（复杂验证）。这个列表本身就是一个极佳的调试思维导图。

第三阶段：系统性验证与信息收集 。AI会按照第二阶段的优先级，逐步指导你进行验证。它会给出具体的、可执行的命令或代码修改建议，并解释每一步预期会看到什么结果。例如，验证代理问题，它会让你在终端执行 curl -v https://api.example.com 并分析输出；验证CORS问题，它会教你打开浏览器开发者工具查看Network标签下的具体错误信息。这个过程是交互式和引导式的，AI扮演着调试伙伴的角色。

第四阶段：根因分析与解决方案设计 。一旦锁定问题根源，AI不会仅仅给出修复代码。它会深入解释问题的本质原因（是理解错误、边界条件缺失还是依赖库版本冲突？），然后提供多个解决方案选项，并分析各自的利弊。例如，修复一个空指针异常，方案A是增加空值检查（快速但可能掩盖设计问题），方案B是重构数据流确保值不为空（根治但改动较大）。这有助于你做出符合项目长期健康的决策。

实操心得 ：不要跳过第一阶段。我曾多次试图让AI直接看一段报错代码，结果它给出的修复只针对了表面症状。后来我强迫自己按照四阶段框架，先写一份清晰的问题报告，AI给出的诊断准确率提升了至少一倍。这个框架在训练你如何与AI高效沟通。

3.2 test 插件：强制执行的红-绿-重构TDD循环

许多开发者知道TDD好，但实践中，无论是自己还是AI，都容易跳过“写一个失败测试”的关键第一步，直接去实现功能。 test 插件的核心价值就是通过流程约束，确保TDD被严格执行。

红阶段：先写一个明确失败的测试 。当你使用 /dotai:create-app-design 或类似命令后，如果涉及新功能， test 插件的 tdd 技能可能会被触发。它会坚持要求你先编写一个描述新功能行为的测试，并且这个测试在当前代码库下 必须失败 。AI会帮你构思这个测试，检查它是否真的在测试你想要的行为，并确保运行测试套件时它能如预期般变红。这个阶段看似“多余”，但它强制澄清了需求：你到底要构建什么？如何验证它已完成？

绿阶段：用最简单的方式让测试通过 。在红阶段完成后，AI才会转向实现。而且它会强调“最简单”的原则：不要过度设计，不要提前优化，代码可以丑，可以重复，唯一的目标就是让那个红色的测试变绿。这能有效防止范围蔓延和过早抽象。AI会给出最直白的实现方案，有时甚至显得“笨拙”，但这恰恰是TDD的精髓——通过小步快跑，持续获得正向反馈。

重构阶段：在绿灯的保护下改善代码 。测试变绿后， test 插件会提示你进入重构阶段。现在你有了一层安全网，可以放心地清理刚才写的“丑陋”代码：提取方法、消除重复、改善命名、应用设计模式。AI会基于当前代码上下文，提出具体的重构建议。因为测试是绿的，你可以确信重构没有破坏任何现有功能。

注意事项 ：这个插件在与Claude Code协作时效果最佳，因为Claude能理解“阶段”的概念并保持状态。如果你中途切换话题或开始另一个任务，可能需要手动用 /dotai 命令重新激活TDD上下文。此外，对于极其简单的增删改查，严格的TDD可能显得繁重，此时可以手动关闭该技能的自动触发，灵活运用。

3.3 dig 插件：深入依赖库腹地的“源码探测器”

当我们遇到一个第三方库的怪异行为，或者文档语焉不详时，最大的障碍是AI（和我们自己）对库的内部实现一无所知，只能基于公开API进行猜测。 dig 插件解决了这个“黑盒”问题。

它的工作流程非常直接：当你提出一个关于特定库（比如 lodash 的 merge 函数在特定场景下的行为）的问题时， dig 技能会被触发。AI会建议并引导你执行类似 dig clone lodash 的命令（具体命令取决于插件实现）。这个命令会在后台将目标库的源代码克隆到一个临时目录。

随后，AI不再是基于文档猜测，而是能 直接分析源码 。它可以定位到相关函数的具体实现，分析其逻辑分支、边界条件处理、依赖的内部函数。然后，它基于真实的代码，给出确切的答案：这个行为是特性还是Bug？参数在这个边界值下会怎样处理？如何绕过一个已知的限制？

例如，我曾疑惑于某个日期处理库在不同时区下的格式化差异。文档没有说明。通过 dig ，AI直接带我看源码，发现了内部调用的 Intl.DateTimeFormat 的配置逻辑，瞬间明白了问题所在，并给出了准确的解决方案和规避建议。

核心技巧 ： dig 最适合用于探究那些文档不完善、行为诡异或你需要进行深度定制的流行库。对于小型或内部库，直接看源码可能更高效。此外，记得在探究完成后清理临时目录，或者利用插件可能提供的缓存机制来提升后续查询速度。

3.4 notification 与 media 插件：提升交互体验的贴心工具

这两个插件虽然不直接参与编码，但极大地改善了与AI协作的长时间工作流的体验。

notification 插件让AI在完成一项耗时任务（如执行完整的测试套件、构建项目、安装依赖）后，可以通过macOS的原生通知系统提醒你。这样你就不需要一直盯着终端或Claude Code的界面等待。你可以切到浏览器查资料，或者休息一下，任务完成后会收到一个轻柔的提示音和通知。这个插件通过简单的集成，将异步协作的理念带了进来。

media 插件则更加智能。它可能通过监听系统状态或特定窗口，在检测到Claude Code开始“思考”或生成长篇输出时，自动暂停你正在播放的音乐或视频；在AI响应完成、等待你输入时，又自动恢复播放。这个功能看似微小，但对于那些喜欢在背景音乐中编码，但又经常被AI的突然发言打断的人来说，是一个巨大的体验提升。它创造了一个更流畅、无干扰的人机交互环境。

4. 复合工程工作流：从规划到交付的自动化流水线

compound-engineering 插件及其相关命令，将dotAI从一个工具集提升到了一个近乎自动化项目交付引擎的水平。 /workflows:lfg 命令是这个理念的集中体现，它串联起了一个完整的开发闭环。

/workflows:brainstorm ：这不是简单的需求收集。这个阶段，AI会扮演产品经理和架构师的双重角色，通过一系列提问帮你深挖模糊的需求。它会问：“这个功能的主要用户是谁？他们的核心痛点是什么？”“有哪些非功能性需求？比如性能指标、安全性要求？”“与现有系统的集成点在哪里？”这个过程产出的不是代码，而是一份经过深思熟虑的需求纲要，为后续规划打下坚实基础。

/workflows:plan ：基于brainstorm的产出，AI开始制定详细的实施计划。这不仅仅是任务列表。它会进行技术选型分析（为什么选React而不是Vue？为什么用PostgreSQL而不是MySQL？），设计高层架构图（即使是文本描述），并拆解出具体的工作项，每个工作项都包含输入、输出、验收标准和可能的风险。这个计划是可执行的蓝图。

/workflows:work ：这是执行阶段。AI会按照计划，逐个攻克工作项。但关键不在于它写代码，而在于它如何写。它会结合 debug 、 test 、 dig 等技能，以结构化的方式推进。例如，实现一个API端点，它会先（通过 test 技能）写集成测试，然后实现逻辑，过程中遇到第三方库问题就用 dig 去研究，最后运行测试并通过 notification 通知你结果。

/workflows:review ：代码写完不是结束。这里会调用多达14个不同的“审查代理”，从不同角度审视代码。 architecture-strategist 看架构一致性， code-simplicity-reviewer 看代码复杂度， security-sentinel 看安全漏洞， performance-oracle 看性能隐患。这相当于一个全天候、全栈的资深团队在为你做代码审查，覆盖面远超单一个人。

/workflows:compound ：最后，AI会将这个过程中解决的关键问题、做出的重要决策、学到的经验教训文档化。这份文档对于项目复盘、知识传承、以及未来处理类似问题极具价值。

整个 lfg 工作流，模拟了一个成熟软件团队的完整开发流程，并将其中大量重复性、模式化的思考和工作自动化，让你能更专注于最具创造性和决策性的部分。

5. 安装、配置与集成实战

5.1 环境准备与初始安装

dotAI的安装方式根据你是否已有Claude Code的配置文件而有所不同，这体现了其设计的灵活性。

对于全新设置 ，项目推荐使用 shadcn/ui 的插件注册表方式。执行 npx shadcn@latest add https://raw.githubusercontent.com/udecode/dotai/main/registry/all.json 这个命令。这条命令的背后，是将dotAI的所有插件作为一个“超级组件”注册到你的Claude Code环境中。 shadcn/ui 在这里更像是一个Claude插件的管理器。执行后，它会修改或创建 .claude/settings.json 文件，将dotAI的插件源添加进去。这种方式干净利落，适合从零开始搭建AI开发环境。

对于已有Claude Code配置的用户 ，dotAI提供了更细粒度的安装方式。你需要手动将插件市场源添加到配置中： /plugin marketplace add https://github.com/udecode/dotai 。这行命令告诉Claude Code，可以去这个GitHub仓库寻找插件。随后，你可以像安装普通插件一样，选择性地安装你需要的部分： /plugin install dotai notification debug test dig codex 。我建议初次使用时安装全部核心插件，以体验完整能力，后续再根据实际使用频率进行删减。

集成官方与社区插件 ：dotAI的设计是开放的。除了自己的生态，它还明确指引你集成其他优质插件。例如，安装官方的 ralph-loop 插件可以获得更强的循环迭代能力， frontend-design 插件则专注于UI/UX设计。而 compound-engineering 插件更是需要从另一个独立的仓库添加市场源后再进行安装。这种“博采众长”的思路，让你能打造一个最适合自己技术栈和工作流的、独一无二的AI开发环境。

5.2 核心配置文件 .claude/prompt.yml 详解

这个YAML文件是控制AI行为的关键。它的结构清晰，但配置需要一些思考。

beforeStart:
  - tag: SKILL-ANALYSIS
    header: 🎯 技能检查点
    todos:
      - “分析当前任务上下文，列出所有可用的dotAI技能（debug, tdd, dig等）”
      - “判断是否有技能适用于当前阶段，如有，则模拟调用该技能的核心检查逻辑”
  - tag: CONTEXT-SETUP
    header: 🧠 上下文初始化
    todos:
      - “明确用户身份：是全栈开发者、前端新手还是后端专家？”
      - “确认项目背景：是React SPA、Node.js API还是Rails单体应用？”
      - “识别当前阶段：是需求分析、编码、调试还是重构？”

beforeComplete:
  - tag: QUALITY-GATE
    header: 🔒 质量门禁
    todos:
      - “代码检查：是否存在明显的语法错误、未使用的变量或导入？”
      - “逻辑自查：提供的解决方案是否完全解决了用户描述的问题？有无遗漏的边缘情况？”
      - “下一步提示：基于当前进展，为用户建议一个最合理的后续操作（如运行测试、查看文档、进行特定调试）”
  - tag: FORMATTING
    header: ✨ 输出格式化
    todos:
      - “确保代码块已标注正确的语言类型（如javascript, python, bash）”
      - “长输出是否使用了标题、列表或表格来增强可读性？”
      - “关键结论或警告是否已使用加粗或引用块突出显示？”

afterCompact:
  - tag: MEMORY-RECOVERY
    header: 💾 关键记忆恢复
    todos:
      - “重新声明我们正在解决的核心问题是什么（用一句话概括）”
      - “复述当前达成共识的技术方案或选型”
      - “列出最近一次成功执行的命令或代码片段及其结果”

配置心得 ：

1. 循序渐进 ：不要一开始就配置得太复杂。可以从 beforeComplete 中的基础质量检查开始，比如添加一条“为新增的TypeScript接口生成示例用法”。
2. 个性化 ：根据你的主要工作内容调整。如果你主要做数据迁移，可以在 beforeStart 中加入“检查源数据和目标模式兼容性”；如果你主要做代码重构，可以在 beforeComplete 中加入“比较重构前后的代码复杂度（如圈复杂度）”。
3. 保持简洁 ：每个 todos 列表中的项目最好不超过3条，且表述要具体、可执行。过于冗长的检查列表会被AI忽略。
4. 测试与迭代 ：配置后，通过几个实际任务观察AI的行为变化。如果发现某个钩子没有生效或效果不佳，调整其描述或调整 tag 的优先级。

5.3 与现有开发流程的融合

引入dotAI不是要颠覆你现有的流程，而是增强它。

与版本控制 ：你的 .claude/settings.json 和 .claude/prompt.yml 文件应该被加入Git仓库。这确保了团队所有成员使用同一套AI协作规范，就像共享 .eslintrc 和 prettierrc 一样。当插件或提示词流程更新时，可以通过Pull Request来讨论和合并，实现流程的版本化管理。

与CI/CD管道 ： compound-engineering 工作流中产生的计划、审查报告，甚至 dotai 生成的技术设计文档，都可以作为CI流程的一部分，自动关联到对应的Issue或Pull Request中。你可以配置GitHub Actions或GitLab CI，在AI完成 /workflows:review 后，自动将审查摘要以评论形式贴到PR中。

与IDE和终端 ：dotAI的大部分交互发生在Claude Code界面内，但其触发的命令（如运行测试、启动调试器）是在你的本地终端或IDE中执行的。确保Claude Code有适当的权限来执行这些命令。一个高效的设置是，将Claude Code窗口和你的代码编辑器、终端并排摆放，形成“AI助手 - 编辑区 - 执行反馈区”的三联屏工作流。

6. 常见问题、排查与效能提升技巧

6.1 安装与配置问题

问题1：执行 npx shadcn@latest add ... 命令时报错“Command not found: shadcn”。

• 原因 ： shadcn/ui 命令行工具未全局安装，或者项目环境有问题。
• 解决 ：首先尝试在项目根目录运行 npx shadcn@latest init 来初始化 shadcn/ui 环境（如果尚未初始化）。如果问题依旧，可以尝试使用 npx -p @shadcn/ui@latest add ... 来显式指定包。最直接的方式是采用手动安装法：直接编辑 .claude/settings.json ，在 plugins 或 marketplace 字段中添加dotAI的GitHub仓库URL。

问题2：插件安装成功，但命令（如 /dotai:create-tech-stack ）无法识别或执行无反应。

• 原因 ：Claude Code的插件系统可能需要刷新或重新加载上下文；或者命令前缀配置有误。
• 解决 ：首先尝试在Claude Code中完全重启会话（关闭并重新打开与当前项目的聊天窗口）。如果不行，检查 .claude/settings.json ，确保dotAI插件已被正确列出且处于启用状态。有时，需要手动输入一次 / 来触发命令补全列表，看看dotAI的命令是否出现。

问题3： .claude/prompt.yml 配置文件似乎没有生效，AI行为无变化。

• 原因 ：YAML格式错误；文件未放在正确路径；Claude Code未读取该配置。
• 解决 ：使用在线YAML校验器检查配置文件语法。确认文件位于项目根目录的 .claude 文件夹下（注意是隐藏文件夹）。在Claude Code中，尝试输入 /system 命令，有时它会显示当前加载的系统提示词或配置来源，可以用于诊断。

6.2 插件使用与效能问题

问题4： debug 插件总是陷入循环提问，迟迟不进入验证阶段。

• 原因 ：问题描述可能仍然不够具体，或者AI在“假设生成”阶段产生了过多模糊的假设。
• 解决 ：主动干预。在AI进行到第二阶段（假设生成）时，你可以根据经验，手动筛选并指定一个你认为最可能的假设，例如说：“我们先重点验证假设2：API密钥权限不足。告诉我具体需要检查哪个配置文件的哪个字段？” 引导AI进入具体的验证步骤。

问题5： test 插件的TDD流程对于快速原型开发显得太慢。

• 原因 ：TDD的优势在于构建稳健、可维护的代码，但对于一次性的、探索性的脚本或原型，其价值确实会打折扣。
• 解决 ：灵活开关。你可以在 .claude/prompt.yml 的 beforeStart 钩子中，通过上下文判断来条件性地跳过 tdd 技能触发。例如，添加一条规则：“如果用户消息中包含‘快速原型’、‘一次性脚本’等关键词，则跳过SKILL-ANALYSIS中的tdd技能检查”。或者，更简单的方式是在对话开始时明确告诉AI：“本次任务我们跳过严格的TDD，以快速实现功能为目标。”

问题6： dig 插件克隆大型仓库（如React）时速度慢，或临时目录占用空间大。

• 原因 ：每次查询都完整克隆仓库。
• 解决 ：查看 dig 插件是否有缓存配置。理想的 dig 实现应该支持本地缓存，第一次克隆后，后续查询复用本地副本。如果没有，可以考虑手动优化：对于你经常需要“深挖”的库，可以提前将其克隆到某个固定目录，然后通过修改插件配置或环境变量，让 dig 指向这个本地目录，而不是每次都从网络克隆。

6.3 高级技巧与自定义扩展

技巧1：创建自定义技能 。dotAI的技能系统是开放的。如果你发现自己反复执行某一类特定操作（例如，为每个新组件生成对应的Storybook故事文件），你可以尝试定义自己的技能。研究现有技能（如 tdd , debug ）在 .claude 目录下的实现方式（通常是JavaScript或Python脚本），模仿其结构创建一个新的技能文件，并在 prompt.yml 中注册它。这能将你的个人工作流模式固化下来。

技巧2：构建专属的MCP服务器 。 codex 插件提到了“MCP servers for Codex”。MCP（Model Context Protocol）是一种让AI模型安全访问外部数据和工具的协议。你可以为自己公司的内部API文档、私有组件库、特定的数据库Schema构建MCP服务器。然后通过 codex 插件集成进来。这样，Claude Code在为你编写调用内部服务的代码时，就能获得准确、实时的上下文信息，极大提升代码的准确性和安全性。

技巧3：与Cursor的“/edit”指令结合 。虽然dotAI主要面向Claude Code，但其理念可以迁移。在Cursor编辑器中，你可以将dotAI的 debug 四阶段框架或TDD流程，编写成一组详细的“/edit”指令预设。例如，创建一个名为“debug:network”的指令预设，其内容就是第一阶段到第四阶段的引导性问题。当遇到网络问题时，直接运行这个预设，Cursor就会引导你完成结构化的调试过程。

技巧4：量化评估与迭代 。使用一段时间后，可以做个回顾：记录下使用dotAI前后，在“解决一个典型Bug”、“实现一个中等复杂度功能”上所花费的时间、交互轮次和代码质量。关注哪些插件/技能使用频率最高，哪些很少用到。根据这些数据，调整你的插件组合和 prompt.yml 配置，形成最适合你个人节奏的“终极配置”。AI辅助工具的价值，最终要体现在开发效率和产出质量的提升上，而这个提升是需要通过实践去度量和优化的。