taskfile

用途

Taskfile Skill 用于创建、调试和重构 Taskfile.yml 或 Taskfile.yaml 自动化配置，基于 go-task 和 task CLI。当用户提到 Taskfile 时即可使用。它面向本地开发、CI 和 monorepo 场景，目标是生成生产级的 Taskfile 自动化。

主要能力

Task 是一个 YAML 任务运行器，具备以下能力：

依赖图（deps）
通过 Go text/template 与 slim-sprig 函数进行模板化
增量执行（sources、generates、status、method）
通过 includes 进行任务组合

使用方式

起步步骤

识别用户目标（开发工作流、构建、测试、发布、代码生成、部署）。
检查现有 Taskfile.yml 与项目脚本（package.json、Makefile、CI 配置）。
决定是：向现有 Taskfile 添加任务、拆分为被 include 的 Taskfile，还是新建一个 Taskfile。

优先选择小型、可组合的任务，并带有清晰的 desc 和可预测的变量。

核心实现规则

根 schema 保持 version: '3'，除非用户需要更严格的 semver 约束。
在面向用户的任务上使用 desc，使 task --list 有用。
对不打算直接调用的辅助任务使用 internal: true。
对可并行的前置任务使用 deps；对有序执行使用 cmds: - task: ...。
使用 requires.vars 强制必填输入，并用 enum 约束提升安全性。
使用 sources + generates（或 status）跳过不必要的工作。
使用 preconditions 做硬失败检查（缺少工具/文件/环境变量）。
使用 if 在不失败的情况下有条件跳过任务。
在子文件夹/服务中运行时使用任务级 dir。

输出期望

编写或编辑 Taskfile 时：

返回可直接运行的合法 YAML；
仅对不明显的行为添加简洁注释；
在有用时至少包含一个默认或清晰记录的入口任务；
在回复中包含调用任务的实用示例（带变量和 -- CLI 参数）。

路由指南

schema 键与合法形状：references/schema-and-model.md
模板化与特殊变量：references/templating-and-vars.md
执行模型、缓存与可靠性：references/execution-patterns.md
CLI 标志、调试流程与故障排查：references/cli-and-debugging.md
可直接复制的 Taskfile：examples/basic-taskfile.yml、examples/monorepo-taskfile.yml

适用场景

高价值模式

安全部署任务
- 提示确认
- 用 requires.vars 选择环境
- 用 preconditions 检查必需的密钥/工具
快速本地开发循环
- 顶层 dev 任务分发到各服务任务
- 在合适处使用 watch
- 为常用命令提供清晰的任务别名
增量构建/代码生成
- 用 sources 和 generates 实现确定性的重复运行
- 对内容敏感的工作流使用 method: checksum
- 仅在需要文件系统 mtime 行为时使用 method: timestamp
Monorepo 组合
- 带命名空间的 includes
- 仅在命名冲突可控时使用 flatten
- 用 excludes 处理冲突的任务名

限制与反模式

应避免的反模式：

隐藏多个关注点的巨型单一任务。
依赖不同命令之间共享的 shell 状态。
在面向用户的任务上省略 desc。
习惯性使用 --force，而不是正确建模 sources/status。
在 env/dotenv 更合适时，把敏感值直接放进 Taskfile。

最小质量检查清单

完成前请验证：

task --list 可读且有意义。
必填变量被强制（requires）。
任务从预期目录运行（dir，必要时 USER_WORKING_DIR）。
增量任务具有正确的失效判断（sources/generates/status）。
任务名与命名空间一致且可预测。