Task Master 工程开发规约CLAUDE.md 驱动的架构分层、测试纪律与代码质量实践指南【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-masterTask Mastertm-core是一个可嵌入 Cursor、Lovable、Windsurf、Roo 等 AI 编码环境的 AI 任务管理系统其 CLAUDE.md 是指导 Claude Code 等 AI Agent 在本仓库内协作开发的开发规约它定义了测试文件的放置规则、同步测试纪律、测试编写边界、业务逻辑分层架构以及代码复用与变更集管理流程。本文以该文件为主线结合仓库源码与测试用例逐条解读这些规约背后的工程理由与落地方式帮助贡献者无论是人类还是 AI Agent快速写出符合项目预期的代码。读完本文你将掌握如何为 Task Master 的各个包正确放置并编写测试为什么tm/core是唯一承载业务逻辑的层而 CLI / MCP 只能是薄表现层以及如何通过 changeset 与类型检查完成一次合规的代码变更。一、总览这份 CLAUDE.md 在规约什么CLAUDE.md 是 Claude Code 系列工具的指令文件本仓库根目录的 CLAUDE.md 扮演双重角色导入 Task Master 开发工作流第 1 行通过./.taskmaster/CLAUDE.md将 Task Master 的开发命令与准则引入到主指令中等同于把任务管理系统的开发流程视为仓库协作的一部分。定义工程约束从测试放置、测试风格、架构分层、代码质量到变更集管理全文是一套可被 Agent 逐条执行的工程纪律。仓库采用 monorepo 结构见根目录 package.json 与 turbo.json核心工作区包括工作区目录角色tm/corepackages/tm-core全部业务逻辑、领域模型、服务与工具tm/cliapps/cli薄表现层命令解析、输出格式化、用户交互tm/mcpapps/mcp薄表现层MCP 工具 schema、参数校验、响应格式化VS Code 扩展apps/extension未来的薄表现层调用 tm-core 并在 VS Code UI 中展示二、测试文件放置贴近源码、类型统一2.1 放置规则规约对测试文件的位置做了严格约束原则是测试与源码并肩放置包级单元测试packages/package-name/src/module/file.spec.ts或apps/app-name/src/module/file.spec.ts与源码放在同一模块目录包级集成测试packages/package-name/tests/integration/module/file.test.ts或apps/app-name/tests/integration/module/file.test.ts隔离单元测试仅当无法与源码并列放置时才使用tests/unit/packages/package-name/统一使用.ts扩展名TypeScript 测试一律用.ts绝不用.js。仓库现状与这一约定高度吻合。例如tm/core中 task-id.schema.spec.ts 与其源码 task-id.schema.ts 同目录CLI 侧 loop.command.spec.ts 与 loop.command.ts 并列集成测试则落在 packages/tm-core/tests/integration 与 apps/cli/tests/integration 下。2.2 为什么这样放可发现性打开某个模块的源码目录就能看到对应测试Agent 与人类都无需跨目录猜测路径相对稳定测试与被测代码的相对位置固定便于推导 import 路径职责清晰.spec.ts单元、隔离与.test.ts集成的命名区分了测试粒度。三、同步测试纪律默认不要 async/await规约强调测试函数默认应为同步仅在真正测试异步操作时才使用async/await禁止在测试函数中使用async/await除非被测行为本身就是异步的用顶层同步 import代替动态await import()测试体尽量保持同步。规约给出的正反例// ✅ 正确——同步 import使用 .ts 扩展名 import { MyClass } from ../src/my-class.js; it(should verify behavior, () { expect(new MyClass().property).toBe(value); }); // ❌ 错误——异步 import it(should verify behavior, async () { const { MyClass } await import(../src/my-class.js); expect(new MyClass().property).toBe(value); });同步测试带来更快的启动与执行速度、更稳定的断言时序无需处理 Promise 竞态也让测试结果更容易被 Agent 解析与复现。需要说明的是当被测对象本身是异步 API例如await tmCore.tasks.list(...)时测试依然要使用 async规约禁止的是为了写测试而引入的不必要异步。四、何时写测试写什么、跳过什么4.1 必须写测试的场景场景说明Bug 修复先写一个能复现该 bug 的回归测试业务逻辑复杂计算、校验、转换逻辑边界条件边界值、错误处理、null/undefined 场景公共 API其他代码依赖的方法集成点数据库、文件系统、外部 API4.2 跳过测试的场景简单的 getter/settergetX() { return this.x; }无逻辑的透传函数pass-through纯配置对象仅委托给其他已被测试函数的代码规约给出的判断示例// ✅ 写测试——带回归预防的 bug 修复 it(should use correct baseURL from defaultBaseURL config, () { const provider new ZAIProvider(); expect(provider.defaultBaseURL).toBe(https://api.z.ai/api/paas/v4/); }); // ✅ 写测试——带边界条件的业务逻辑 it(should parse subtask IDs correctly, () { expect(parseTaskId(1.2.3)).toEqual({ taskId: 1, subtaskId: 2, subSubtaskId: 3 }); expect(parseTaskId(invalid)).toBeNull(); }); // ❌ 跳过测试——琐碎的 getter class Task { get id() { return this._id; } // 无需测试 } // ❌ 跳过测试——纯委托 function getTasks() { return taskManager.getTasks(); // 已在 taskManager 中测试 }4.3 Bug 修复工作流遇到 bug写一个能复现它的失败测试修复 bug验证测试通过将修复与测试一起提交。这正是 apps/cli/tests/integration/commands/list.command.test.ts 中错误处理一节的实践模式测试构造缺少description或title的非法任务数据断言 CLI 退出码为 1、输出包含校验错误关键词且不包含被包装后的泛化错误信息not.toContain(Failed to get task list)从而确保校验错误能原样透出到 CLI 层。五、测试方法论FIRST、AAA 与 Right-BICEP5.1 三条原则FIRSTFast快、Independent独立、Repeatable可重复、Self-validating自校验、Timely及时AAAArrange准备、Act执行、Assert断言Right-BICEPRight results正确结果、Boundary边界、Inverse反向验证、Cross-check交叉验证、Error conditions错误条件、Performance性能。5.2 Mock 边界只 mock 你没在测试的东西规约按测试层级给出明确的 mock 策略测试层级Mock 策略tm/core单元测试.spec.ts只 mock 外部 I/OSupabase、API、文件系统内部服务用真实实现apps/cli单元测试mocktm-core的响应但使用真实的Commander / chalk / inquirer 等 npm 包测试展示逻辑apps/mcp单元测试mocktm-core响应使用真实的 MCP 框架测试响应格式化集成测试tests/integration/所有包都使用真实tm-core只 mock 外部边界API、DB、文件系统永远不要 mock同包内的内部工具/辅助函数标准框架Commander、Express——让它们真实运行标准库。经验法则mock 你没在测试的东西。CLI 单元测试测展示逻辑 → mock tm-corecore 单元测试测逻辑 → mock I/O集成测试测完整流程 → 只 mock 外部 API。红旗信号一个单元测试 mock 了 3 个以上依赖意味着该代码职责过多或处于错误的层。反模式警示重度 mock 的测试验证的不是真实行为而是你正确接好了 mock。这会导致你为了满足测试而编写编排代码而不是让测试验证真实实现。如果测试难写就把逻辑移到天然可测的地方。一个落地实例CLI 侧 loop.command.spec.ts 用vi.mock(tm/core, ...)只 mock 了createTmCore与PRESET_NAMES同时 mock 了display-helpers、error-handler、project-root等展示辅助模块而让 Commander 等框架真实运行——与规约的CLI 单元测试测展示逻辑 → mock tm-core完全一致。六、架构准则业务逻辑必须住在 tm/core6.1 CRITICAL RULE业务逻辑只属于 coretm/corepackages/tm-core包含所有业务逻辑、领域模型、服务与工具通过领域对象tasks、auth、workflow、git、config提供干净的 facade API承载全部复杂性——解析、校验、转换、计算等示例任务 ID 解析、子任务提取、状态校验、依赖解析。tm/cliapps/cli仅作为薄表现层调用 tm-core 方法并展示结果处理 CLI 专属关注点参数解析、输出格式化、用户提示不含业务逻辑、数据转换、计算。tm/mcpapps/mcp仅作为薄表现层调用 tm-core 方法并返回 MCP 格式响应处理 MCP 专属关注点工具 schema、参数校验、响应格式化不含业务逻辑。apps/extension未来的薄表现层调用 tm-core 方法并在 VS Code UI 中展示不含业务逻辑。6.2 需要避免的违规示例❌ 在 CLI/MCP 中创建辅助函数解析任务 ID → 移到 tm-core❌ CLI/MCP 中的数据转换逻辑 → 移到 tm-core❌ CLI/MCP 中的校验逻辑 → 移到 tm-core❌ 在 CLI 与 MCP 间复制逻辑 → 在 tm-core 中实现一次。6.3 正确做法统一的智能 ID 解析✅ 在 TasksDomain 添加方法tasks.get(taskId)自动处理任务与子任务 ID✅ CLI 调用await tmCore.tasks.get(taskId)支持1、1.2、HAM-123、HAM-123.2✅ MCP 调用await tmCore.tasks.get(taskId)同样的智能 ID 解析✅ 单一事实来源single source of truth落在 tm-core。源码证据统一门面 packages/tm-core/src/tm-core.ts 是使用 tm-core 的唯一入口通过createTmCore({ projectPath })创建实例后可访问tmcore.tasks、tmcore.auth、tmcore.workflow、tmcore.git、tmcore.config、tmcore.integration、tmcore.loop七大领域门面。任务 ID 的解析与校验集中在 packages/tm-core/src/modules/tasks/validation/task-id.tsTASK_ID_PATTERN /^(\d(\.\d)*|[A-Za-z]-?\d)$/同时接受数字1、1.2、1.2.3与带前缀的 API IDHAM-1、PROJ-456并明确拒绝HAM-1.2这类不存在的 API 子任务。ID 规范化逻辑位于 packages/tm-core/src/common/schemas/task-id.schema.ts 的normalizeDisplayId()文件存储的数字 ID1、1.1原样返回API ID 无论输入是ham1、HAM1还是ham-1统一规范化为HAM-1大写带连字符格式。CLI 侧 apps/cli/src/commands/list.command.ts 则印证了薄表现层的定位它从tm/core导入createTmCore、buildBlocksMap、filterReadyTasks等能力仅负责参数解析Commander、过滤组合与表格渲染所有任务获取都委托给this.tmCore.tasks.list(...)。七、代码质量与复用准则规约要求应用标准的软件工程原则DRYDont Repeat Yourself出现 2 次以上的模式应抽取为可复用组件或工具YAGNIYou Arent Gonna Need It不要过度设计在重复出现时才创建抽象而不是提前可维护性Maintainable单一事实来源改一处、处处生效可读性Readable命名清晰、结构合理、从 index 文件统一导出灵活性Flexible接受带合理默认值的配置选项。这条准则在 tm-core 的门面设计上体现得最明显CLI 与 MCP 两个消费方都通过tmCore.tasks.get(taskId)获得同一套智能 ID 解析业务逻辑只实现一次避免跨层复制。八、文档与变更集Changeset准则8.1 文档放置文档位置写在apps/docs/Mintlify 站点源码中而不是仓库根部的docs/。仓库中 apps/docs 目录确实承载了 quick-start、capabilities、best-practices、tdd-workflow 等文档章节.mdx格式。文档引用指向 Task Master 官方文档地址而非本地文件路径。8.2 变更集管理为代码变更添加 changeset修改代码后运行npx changeset仅文档变更的 PR 不需要changeset 面向用户描述的是终端用户获得什么、修复什么而不是代码内部细节推送前运行类型检查npm run turbo:typecheck确保 TypeScript 类型全部通过按包测试npm run test -w package-name测试指定包。这套流程与仓库根目录的 turbo.jsonTurbo 任务编排以及各包独立的vitest.config.ts如 apps/cli/vitest.config.ts、packages/tm-core/vitest.config.ts 相互呼应monorepo 中以包为单位运行测试与类型检查。九、实践要点速查测试放置单元测试.spec.ts与源码同目录集成测试.test.ts放tests/integration/一律.ts扩展名。同步优先默认同步测试与顶层 import除非被测行为本身异步。Mock 边界mock 你没在测试的东西单元测试 mock 超过 3 个依赖即为红旗。架构铁律任何解析、校验、转换、计算逻辑都必须进tm/coreCLI/MCP 只做参数处理与展示。复用原则DRY、YAGNI、单一事实来源避免在 CLI 与 MCP 之间复制逻辑。变更流程改代码 →npx changeset→npm run turbo:typecheck→npm run test -w package-name。这份 CLAUDE.md 的价值在于把架构分层、测试纪律、质量红线固化成可被 AI Agent 逐条执行的指令无论贡献者是 Claude Code、其他编码 Agent 还是人类开发者只要遵循这套规约就能保证业务逻辑集中在tm/core、测试可信且可维护、变更可追踪——这正是 Task Master 作为可嵌入多种 AI 编码环境的项目能够长期保持工程一致性的底层机制。【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考