aif-build-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Automation Generator

构建自动化生成器

Generate or enhance a build automation file for any project. Supports Makefile, Taskfile.yml, Justfile, and Magefile.go.

Two modes:

Generate — No build file exists → create one from scratch using best-practice templates
Enhance — Build file already exists → analyze gaps, add missing targets, fix anti-patterns, preserve existing work

为任意项目生成或增强构建自动化文件。支持Makefile、Taskfile.yml、Justfile和Magefile.go。

两种模式：

生成 — 无构建文件存在 → 使用最佳实践模板从头创建
增强 — 已存在构建文件 → 分析不足，添加缺失的目标，修复反模式，保留现有内容

Step 0: Load Project Context

步骤0：加载项目上下文

Read the project description if available:

Read .ai-factory/DESCRIPTION.md

Store the project context (tech stack, framework, architecture) for use in later steps. If the file doesn't exist, that's fine — we'll detect everything in Step 2.

Read
.ai-factory/skill-context/aif-build-automation/SKILL.md
— MANDATORY if the file exists.

This file contains project-specific rules accumulated by

/aif-evolve

from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

Treat them as project-level overrides for this skill's general instructions
When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
CRITICAL: skill-context rules apply to ALL outputs of this skill — including the generated build files (Makefile, Taskfile, justfile, magefile). Templates in this skill are base structures. If a skill-context rule says "build file MUST include target X" or "MUST follow convention Y" — you MUST comply. Generating build automation that violates skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

如果有项目描述，请阅读：

Read .ai-factory/DESCRIPTION.md

存储项目上下文（技术栈、框架、架构）供后续步骤使用。如果该文件不存在也没关系——我们会在步骤2中自动检测所有信息。

读取
.ai-factory/skill-context/aif-build-automation/SKILL.md
— 如果文件存在，此步骤为必填项。

该文件包含由

/aif-evolve

从补丁、代码库约定和技术栈分析中积累的项目特定规则。这些规则是为当前项目量身定制的。

如何应用技能上下文规则：

将它们视为本技能通用指令的项目级覆盖规则
当技能上下文规则与本SKILL.md中的通用规则冲突时，技能上下文规则优先（更具体的上下文优先级更高——与嵌套CLAUDE.md文件的原则相同）
无冲突时，同时应用两者：SKILL.md中的通用规则 + 技能上下文的项目规则
即使技能上下文规则似乎与本技能的默认设置相矛盾，也不要忽略它们——这些规则存在是因为项目实践证明默认设置不足
关键提示： 技能上下文规则适用于本技能的所有输出——包括生成的构建文件（Makefile、Taskfile、justfile、magefile）。本技能中的模板是基础结构。如果技能上下文规则规定“构建文件必须包含目标X”或“必须遵循约定Y”——则必须遵守。生成违反技能上下文规则的构建自动化内容属于错误。

执行要求： 生成任何输出工件后，需对照所有技能上下文规则进行验证。如果违反任何规则——在呈现给用户之前修复输出内容。

Step 1: Detect Existing Build Files & Determine Mode

步骤1：检测现有构建文件并确定模式

1.1 Scan for Existing Build Files

1.1 扫描现有构建文件

Before anything else, check if the project already has build automation:

Glob: Makefile, makefile, GNUmakefile, Taskfile.yml, Taskfile.yaml, taskfile.yml, justfile, Justfile, .justfile, magefile.go, magefiles/*.go

Build a list of

EXISTING_FILES

from the results.

首先，检查项目是否已有构建自动化文件：

Glob: Makefile, makefile, GNUmakefile, Taskfile.yml, Taskfile.yaml, taskfile.yml, justfile, Justfile, .justfile, magefile.go, magefiles/*.go

从扫描结果中构建

EXISTING_FILES

列表。

1.2 Determine Mode

1.2 确定模式

Mode A — Enhance Existing (if

EXISTING_FILES

is not empty):

Set
```
MODE = "enhance"
```
Set
```
TARGET_TOOL
```
automatically from the detected file (Makefile →
```
makefile
```
, Taskfile.yml →
```
taskfile
```
, etc.)
If multiple build files exist AND
```
$ARGUMENTS
```
specifies one, use the argument to pick which one to enhance
If multiple build files exist AND no argument, ask which one to enhance:

AskUserQuestion: This project has multiple build files. Which one should I improve?

Options (dynamic, based on what exists):
1. Makefile — Enhance the existing Makefile
2. Taskfile.yml — Enhance the existing Taskfile
...

Read the existing file content — this is the baseline for enhancement
Store as
```
EXISTING_CONTENT
```

Mode B — Generate New (if

EXISTING_FILES

is empty):

Set
```
MODE = "generate"
```
Parse
```
$ARGUMENTS
```
to determine tool:

Argument	Tool	Output File
`makefile` or `make`	GNU Make	`Makefile`
`taskfile` or `task`	Taskfile	`Taskfile.yml`
`justfile` or `just`	Just	`justfile`
`mage` or `magefile`	Mage	`magefile.go`

If
```
$ARGUMENTS
```
is empty or doesn't match, ask the user interactively:

AskUserQuestion: Which build automation tool do you want to generate?

Options:
1. Makefile — GNU Make (universal, no install needed)
2. Taskfile.yml — Task runner (YAML, modern, cross-platform)
3. justfile — Just command runner (simple, fast, ergonomic)
4. magefile.go — Mage (Go-native, type-safe, no shell scripts)

Store the chosen tool as

TARGET_TOOL

模式A — 增强现有文件（如果

EXISTING_FILES

非空）：

设置
```
MODE = "enhance"
```
根据检测到的文件自动设置
```
TARGET_TOOL
```
（Makefile →
```
makefile
```
，Taskfile.yml →
```
taskfile
```
等）
如果存在多个构建文件且
```
$ARGUMENTS
```
指定了其中一个，则使用该参数选择要增强的文件
如果存在多个构建文件且无参数，则询问用户选择：

AskUserQuestion: 该项目有多个构建文件。您希望改进哪一个？

选项（根据实际存在的文件动态生成）：
1. Makefile — 增强现有Makefile
2. Taskfile.yml — 增强现有Taskfile
...

读取现有文件内容——这是增强的基准
存储为
```
EXISTING_CONTENT
```

模式B — 生成新文件（如果

EXISTING_FILES

为空）：

设置
```
MODE = "generate"
```
解析
```
$ARGUMENTS
```
以确定工具：

参数	工具	输出文件
`makefile` 或 `make`	GNU Make	`Makefile`
`taskfile` 或 `task`	Taskfile	`Taskfile.yml`
`justfile` 或 `just`	Just	`justfile`
`mage` 或 `magefile`	Mage	`magefile.go`

如果
```
$ARGUMENTS
```
为空或不匹配，则交互式询问用户：

AskUserQuestion: 您希望生成哪种构建自动化工具？

选项：
1. Makefile — GNU Make（通用，无需安装）
2. Taskfile.yml — 任务运行器（YAML格式，现代化，跨平台）
3. justfile — Just命令运行器（简洁、快速、易用）
4. magefile.go — Mage（Go原生，类型安全，无需Shell脚本）

将选择的工具存储为

TARGET_TOOL

。

Step 2: Analyze Project

步骤2：分析项目

Detect the project profile by scanning the repository. Run these checks using

Glob

and

Grep

通过扫描仓库检测项目概况。使用

Glob

和

Grep

执行以下检查：

2.1 Primary Language

2.1 主语言

Check for these files (first match wins):

File	Language
`go.mod`	Go
`package.json`	Node.js / JavaScript / TypeScript
`pyproject.toml` or `setup.py` or `setup.cfg`	Python
`Cargo.toml`	Rust
`composer.json`	PHP
`Gemfile`	Ruby
`build.gradle` or `pom.xml`	Java/Kotlin
`.csproj` or `.sln`	C# / .NET

检查以下文件（第一个匹配项生效）：

文件	语言
`go.mod`	Go
`package.json`	Node.js / JavaScript / TypeScript
`pyproject.toml` 或 `setup.py` 或 `setup.cfg`	Python
`Cargo.toml`	Rust
`composer.json`	PHP
`Gemfile`	Ruby
`build.gradle` 或 `pom.xml`	Java/Kotlin
`.csproj` 或 `.sln`	C# / .NET

2.2 Package Manager

2.2 包管理器

Check lock files:

File	Package Manager
`bun.lockb`	bun
`pnpm-lock.yaml`	pnpm
`yarn.lock`	yarn
`package-lock.json`	npm
`poetry.lock`	poetry
`uv.lock`	uv
`Pipfile.lock`	pipenv

检查锁文件：

文件	包管理器
`bun.lockb`	bun
`pnpm-lock.yaml`	pnpm
`yarn.lock`	yarn
`package-lock.json`	npm
`poetry.lock`	poetry
`uv.lock`	uv
`Pipfile.lock`	pipenv

2.3 Framework Detection

2.3 框架检测

For Node.js projects, check

package.json

dependencies for:

```
next
```
→ Next.js
```
nuxt
```
→ Nuxt
```
@remix-run/node
```
→ Remix
```
express
```
→ Express
```
fastify
```
→ Fastify
```
hono
```
→ Hono
```
@nestjs/core
```
→ NestJS

For Python projects, check

pyproject.toml

or imports for:

```
fastapi
```
→ FastAPI
```
django
```
→ Django
```
flask
```
→ Flask

For PHP projects, check

composer.json

require for:

```
laravel/framework
```
→ Laravel
```
symfony/framework-bundle
```
→ Symfony
```
slim/slim
```
→ Slim
```
cakephp/cakephp
```
→ CakePHP

For Go projects, check

go.mod

for:

```
gin-gonic/gin
```
→ Gin
```
labstack/echo
```
→ Echo
```
gofiber/fiber
```
→ Fiber
```
go-chi/chi
```
→ Chi

对于Node.js项目，检查

package.json

依赖项中的：

```
next
```
→ Next.js
```
nuxt
```
→ Nuxt
```
@remix-run/node
```
→ Remix
```
express
```
→ Express
```
fastify
```
→ Fastify
```
hono
```
→ Hono
```
@nestjs/core
```
→ NestJS

对于Python项目，检查

pyproject.toml

或导入语句中的：

```
fastapi
```
→ FastAPI
```
django
```
→ Django
```
flask
```
→ Flask

对于PHP项目，检查

composer.json

中的require项：

```
laravel/framework
```
→ Laravel
```
symfony/framework-bundle
```
→ Symfony
```
slim/slim
```
→ Slim
```
cakephp/cakephp
```
→ CakePHP

对于Go项目，检查

go.mod

中的：

```
gin-gonic/gin
```
→ Gin
```
labstack/echo
```
→ Echo
```
gofiber/fiber
```
→ Fiber
```
go-chi/chi
```
→ Chi

2.4 Docker (Deep Scan)

2.4 Docker深度扫描

Glob: Dockerfile, Dockerfile.*, docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml, .dockerignore

If any exist, set

HAS_DOCKER=true

and perform a deeper analysis:

Read the Dockerfile(s) to detect:

Multi-stage builds (separate
```
dev
```
/
```
prod
```
stages) →
```
DOCKER_MULTISTAGE=true
```
Exposed ports →
```
DOCKER_PORTS
```
(e.g.,
```
3000
```
,
```
8080
```
)
Base image →
```
DOCKER_BASE
```
(e.g.,
```
node:20-alpine
```
,
```
golang:1.22
```
)
Entrypoint/CMD → understand how the app is started inside the container

Read docker-compose / compose file to detect:

Service names →
```
DOCKER_SERVICES
```
(e.g.,
```
app
```
,
```
db
```
,
```
redis
```
,
```
worker
```
)
Volume mounts → understand dev vs prod setup
Profiles (if any) →
```
dev
```
,
```
production
```
,
```
test
```
Dependency services (postgres, redis, rabbitmq, etc.) →
```
DOCKER_DEPS
```

Store as

DOCKER_PROFILE

```
has_compose
```
: boolean
```
has_multistage
```
: boolean
```
services
```
: list of service names
```
deps
```
: list of infrastructure services (db, cache, queue)
```
ports
```
: exposed ports
```
has_dev_stage
```
: boolean (Dockerfile has a
```
dev
```
or
```
development
```
stage)

Glob: Dockerfile, Dockerfile.*, docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml, .dockerignore

如果存在任何上述文件，设置

HAS_DOCKER=true

并执行深度分析：

读取Dockerfile以检测：

多阶段构建（分离
```
dev
```
/
```
prod
```
阶段）→
```
DOCKER_MULTISTAGE=true
```
暴露端口 →
```
DOCKER_PORTS
```
（例如：
```
3000
```
、
```
8080
```
）
基础镜像 →
```
DOCKER_BASE
```
（例如：
```
node:20-alpine
```
、
```
golang:1.22
```
）
Entrypoint/CMD → 了解容器内应用的启动方式

读取docker-compose / compose文件以检测：

服务名称 →
```
DOCKER_SERVICES
```
（例如：
```
app
```
、
```
db
```
、
```
redis
```
、
```
worker
```
）
卷挂载 → 了解开发与生产环境的设置
配置文件（如果有）→
```
dev
```
、
```
production
```
、
```
test
```
依赖服务（postgres、redis、rabbitmq等）→
```
DOCKER_DEPS
```

存储为

DOCKER_PROFILE

：

```
has_compose
```
: 布尔值
```
has_multistage
```
: 布尔值
```
services
```
: 服务名称列表
```
deps
```
: 基础设施服务列表（数据库、缓存、队列）
```
ports
```
: 暴露端口
```
has_dev_stage
```
: 布尔值（Dockerfile包含
```
dev
```
或
```
development
```
阶段）

2.5 CI/CD

Glob: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, .travis.yml

Note which CI system is in use.

Glob: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, .travis.yml

记录使用的CI系统。

2.6 Database & Migrations

2.6 数据库与迁移

Search for migration tools:

Grep: prisma|drizzle|knex|typeorm|sequelize|alembic|django.*migrate|goose|migrate|atlas|sqlx

Check for:

```
prisma/schema.prisma
```
→ Prisma
```
drizzle.config.ts
```
→ Drizzle
```
alembic/
```
directory → Alembic
```
migrations/
```
directory → Generic migrations

搜索迁移工具：

Grep: prisma|drizzle|knex|typeorm|sequelize|alembic|django.*migrate|goose|migrate|atlas|sqlx

检查：

```
prisma/schema.prisma
```
→ Prisma
```
drizzle.config.ts
```
→ Drizzle
```
alembic/
```
目录 → Alembic
```
migrations/
```
目录 → 通用迁移

2.7 Test Framework

2.7 测试框架

Language	Check For
Node.js	`jest` , `vitest` , `mocha` , `ava` in package.json
Python	`pytest` in pyproject.toml/requirements, `unittest` imports
Go	Go has built-in testing; check for `testify` in go.mod
Rust	Built-in; check for integration test directory `tests/`

语言	检查内容
Node.js	`package.json` 中的 `jest` 、 `vitest` 、 `mocha` 、 `ava`
Python	`pyproject.toml` /requirements中的 `pytest` 、 `unittest` 导入
Go	Go内置测试；检查 `go.mod` 中的 `testify`
Rust	内置测试；检查集成测试目录 `tests/`

2.8 Linters & Formatters

2.8 代码检查器与格式化工具

Glob: .eslintrc*, eslint.config.*, .prettierrc*, biome.json, .golangci.yml, .golangci.yaml
Grep in pyproject.toml: ruff|black|flake8|pylint|isort

Glob: .eslintrc*, eslint.config.*, .prettierrc*, biome.json, .golangci.yml, .golangci.yaml
Grep in pyproject.toml: ruff|black|flake8|pylint|isort

2.9 Monorepo Detection

2.9 单仓库检测

Glob: turbo.json, nx.json, lerna.json, pnpm-workspace.yaml

Glob: turbo.json, nx.json, lerna.json, pnpm-workspace.yaml

Summary

总结

Build a

PROJECT_PROFILE

object with:

```
language
```
: primary language
```
package_manager
```
: detected PM
```
framework
```
: detected framework (if any)
```
has_docker
```
: boolean
```
docker_profile
```
:
```
DOCKER_PROFILE
```
object (if
```
has_docker
```
)
```
ci_system
```
: detected CI (if any)
```
has_migrations
```
: boolean + tool name
```
test_framework
```
: detected test runner
```
linters
```
: list of detected linters
```
is_monorepo
```
: boolean
```
has_dev_server
```
: boolean (framework with dev server)

构建

PROJECT_PROFILE

对象，包含：

```
language
```
: 主语言
```
package_manager
```
: 检测到的包管理器
```
framework
```
: 检测到的框架（如果有）
```
has_docker
```
: 布尔值
```
docker_profile
```
:
```
DOCKER_PROFILE
```
对象（如果
```
has_docker
```
为真）
```
ci_system
```
: 检测到的CI系统（如果有）
```
has_migrations
```
: 布尔值 + 工具名称
```
test_framework
```
: 检测到的测试运行器
```
linters
```
: 检测到的代码检查器列表
```
is_monorepo
```
: 布尔值
```
has_dev_server
```
: 布尔值（带开发服务器的框架）

Step 3: Read Best Practices

步骤3：读取最佳实践

Read the best practices reference for the chosen tool:

Read skills/build-automation/references/BEST-PRACTICES.md

Focus on the section matching

TARGET_TOOL

Makefile → Section 1
Taskfile → Section 2
Justfile → Section 3
Magefile → Section 4

Also read the "Cross-Cutting Concerns" section for standard targets.

读取所选工具的最佳实践参考：

Read skills/build-automation/references/BEST-PRACTICES.md

重点关注与

TARGET_TOOL

匹配的章节：

Makefile → 第1节
Taskfile → 第2节
Justfile → 第3节
Magefile → 第4节

同时阅读“跨领域关注点”章节以了解标准目标。

Step 4: Select & Read Template

步骤4：选择并读取模板

Pick the closest matching template based on

language

TARGET_TOOL

Tool	Go	Node.js	Python	PHP	Other
Makefile	`makefile-go.mk`	`makefile-node.mk`	`makefile-python.mk`	`makefile-php.mk`	Use closest match
Taskfile	`taskfile-go.yml`	`taskfile-node.yml`	`taskfile-python.yml`	`taskfile-php.yml`	Use closest match
Justfile	`justfile-go`	`justfile-node`	`justfile-python`	`justfile-php`	Use closest match
Magefile	`magefile-basic.go`	`magefile-full.go`	`magefile-full.go`	N/A (use Makefile)	`magefile-basic.go`

For Magefile: use

magefile-full.go

HAS_DOCKER

has_migrations

is true, otherwise

magefile-basic.go

For PHP + Magefile: Mage is Go-specific and not applicable to PHP projects. If the user explicitly requested

mage

for a PHP project, explain this and suggest Makefile as the closest alternative (universal, no install needed). Ask via

AskUserQuestion

whether to proceed with Makefile instead.

Read the selected template:

Read skills/build-automation/templates/<selected-template>

根据

language

TARGET_TOOL

选择最匹配的模板：

工具	Go	Node.js	Python	PHP	其他
Makefile	`makefile-go.mk`	`makefile-node.mk`	`makefile-python.mk`	`makefile-php.mk`	使用最接近的匹配项
Taskfile	`taskfile-go.yml`	`taskfile-node.yml`	`taskfile-python.yml`	`taskfile-php.yml`	使用最接近的匹配项
Justfile	`justfile-go`	`justfile-node`	`justfile-python`	`justfile-php`	使用最接近的匹配项
Magefile	`magefile-basic.go`	`magefile-full.go`	`magefile-full.go`	N/A（使用Makefile）	`magefile-basic.go`

对于Magefile：如果

HAS_DOCKER

或

has_migrations

为真，则使用

magefile-full.go

，否则使用

magefile-basic.go

。

对于PHP + Magefile：Mage是Go专用工具，不适用于PHP项目。如果用户明确要求为PHP项目使用

mage

，请解释这一点并建议使用Makefile作为最接近的替代方案（通用，无需安装）。通过

AskUserQuestion

询问是否改用Makefile继续。

读取所选模板：

Read skills/build-automation/templates/<selected-template>

Step 5: Generate or Enhance File

步骤5：生成或增强文件

Mode B — Generate New File

模式B — 生成新文件

Using the

PROJECT_PROFILE

, best practices, and template as reference, generate a customized build file from scratch.

使用

PROJECT_PROFILE

、最佳实践和模板作为参考，从头生成定制化的构建文件。

Generation Rules

生成规则

Start with the tool's required preamble (from best practices)
Include all standard targets: help/default, build, test, lint, clean, dev, fmt
Add conditional targets based on project profile:
- Docker targets → only if
```
has_docker
```
- Database targets → only if
```
has_migrations
```
  (use correct migration tool)
- Deploy targets → only if CI/CD detected
- Generate target → only if code generation detected
- Typecheck target → only if TypeScript or mypy detected
Use correct package manager commands (not hardcoded npm/pip/go)
Include CI aggregate target that runs lint + test + build
Follow the template's structure for organization and grouping
Adapt variable names to match the actual project (module name, binary name, source dirs)
Include version/commit/build-time detection via git
Docker-aware targets — if
```
has_docker
```
, generate a dedicated Docker section (see below)

以工具要求的序言开头（来自最佳实践）
包含所有标准目标：help/default、build、test、lint、clean、dev、fmt
根据项目概况添加条件目标：
- Docker目标 → 仅当
```
has_docker
```
  为真时
- 数据库目标 → 仅当
```
has_migrations
```
  为真时（使用正确的迁移工具）
- 部署目标 → 仅当检测到CI/CD时
- 生成目标 → 仅当检测到代码生成工具时
- 类型检查目标 → 仅当检测到TypeScript或mypy时
使用正确的包管理器命令（不硬编码npm/pip/go）
包含CI聚合目标，运行lint + test + build
遵循模板的结构进行组织和分组
调整变量名称以匹配实际项目（模块名称、二进制名称、源目录）
通过git包含版本/提交/构建时间检测
Docker感知目标 — 如果
```
has_docker
```
为真，生成专门的Docker章节（见下文）

Docker-Aware Target Generation

Docker感知目标生成

When

has_docker

is true, generate two layers of commands:

Layer 1 — Container lifecycle (always when Docker detected):

Target	Purpose
`docker-build` or `docker:build`	Build the Docker image
`docker-run` or `docker:run`	Run the container
`docker-stop` or `docker:stop`	Stop running containers
`docker-logs` or `docker:logs`	Tail container logs
`docker-push` or `docker:push`	Push image to registry
`docker-clean` or `docker:clean`	Remove images and stopped containers

Layer 2 — Dev vs Production separation (when compose or multistage detected):

##@ Docker — Development
docker-dev:          ## Start all services in dev mode (with hot reload, mounted volumes)
docker-dev-build:    ## Rebuild dev containers
docker-dev-down:     ## Stop dev environment and remove volumes

##@ Docker — Production
docker-prod-build:   ## Build production image (optimized, multi-stage)
docker-prod-run:     ## Run production container locally for testing
docker-prod-push:    ## Push production image to registry

Generation logic:

If
```
has_compose
```
→ use
```
docker compose
```
commands (not
```
docker-compose
```
)
If compose has profiles → use
```
--profile dev
```
/
```
--profile production
```
If
```
has_multistage
```
→ use
```
--target dev
```
for dev builds, no target (or
```
--target production
```
) for prod
If
```
docker_profile.deps
```
exist (db, redis, etc.) → add
```
infra-up
```
/
```
infra-down
```
targets to start/stop only infrastructure services without the app
If compose detected →
```
docker-dev
```
should run
```
docker compose up
```
with correct profile/services
If no compose but Dockerfile →
```
docker-dev
```
should run
```
docker build --target dev
```
+
```
docker run
```
with volume mounts

Layer 3 — Container-based commands (mirror host commands via container):

When the project is Docker-based, also generate container-exec variants so that users who run everything in Docker can use the same targets:

undefined

当

has_docker

为真时，生成两层命令：

第一层 — 容器生命周期（检测到Docker时始终生成）：

目标	用途
`docker-build` 或 `docker:build`	构建Docker镜像
`docker-run` 或 `docker:run`	运行容器
`docker-stop` 或 `docker:stop`	停止运行中的容器
`docker-logs` 或 `docker:logs`	查看容器日志
`docker-push` 或 `docker:push`	将镜像推送到注册表
`docker-clean` 或 `docker:clean`	删除镜像和已停止的容器

第二层 — 开发与生产分离（检测到compose或多阶段构建时）：

##@ Docker — 开发
docker-dev:          ## 以开发模式启动所有服务（支持热重载、卷挂载）
docker-dev-build:    ## 重新构建开发容器
docker-dev-down:     ## 停止开发环境并删除卷

##@ Docker — 生产
docker-prod-build:   ## 构建生产镜像（优化的多阶段构建）
docker-prod-run:     ## 在本地运行生产容器进行测试
docker-prod-push:    ## 将生产镜像推送到注册表

生成逻辑：

如果
```
has_compose
```
为真 → 使用
```
docker compose
```
命令（而非
```
docker-compose
```
）
如果compose包含配置文件 → 使用
```
--profile dev
```
/
```
--profile production
```
如果
```
has_multistage
```
为真 → 开发构建使用
```
--target dev
```
，生产构建不指定目标（或使用
```
--target production
```
）
如果
```
docker_profile.deps
```
存在（数据库、redis等）→ 添加
```
infra-up
```
/
```
infra-down
```
目标以仅启动/停止基础设施服务，不启动应用
如果检测到compose →
```
docker-dev
```
应运行
```
docker compose up
```
并使用正确的配置文件/服务
如果无compose但有Dockerfile →
```
docker-dev
```
应运行
```
docker build --target dev
```
+
```
docker run
```
并挂载卷

第三层 — 基于容器的命令（通过容器镜像主机命令）：

当项目基于Docker时，还生成容器执行变体，以便所有操作都在Docker中运行的用户可以使用相同的目标：

undefined

Run tests inside the container

在容器内运行测试

docker-test: ## Run tests inside the Docker container docker compose exec app [test command]

docker-test: ## 在Docker容器内运行测试 docker compose exec app [测试命令]

Run linter inside the container

在容器内运行代码检查器

docker-lint: ## Run linter inside the Docker container docker compose exec app [lint command]

docker-lint: ## 在Docker容器内运行代码检查器 docker compose exec app [代码检查命令]

Open shell in the container

在容器内打开Shell

docker-shell: ## Open a shell inside the running container docker compose exec app sh


Only generate `docker-*` exec variants if the project appears to be Docker-first (compose file mounts source code as volumes, or no local language runtime setup is apparent).

docker-shell: ## 在运行中的容器内打开Shell docker compose exec app sh


仅当项目明显是Docker优先（compose文件将源代码挂载为卷，或无本地语言运行时设置）时，才生成`docker-*`执行变体。

Customization from Project Profile

根据项目概况定制

Binary name: Use the actual project name from
```
go.mod
```
,
```
package.json
```
, or directory name
Source directory: Use actual src dir (e.g.,
```
src/
```
,
```
app/
```
,
```
cmd/
```
)
Dev server command: Match the framework's dev server (e.g.,
```
next dev
```
,
```
uvicorn --reload
```
,
```
air
```
)
Test command: Match the detected test runner
Lint command: Match the detected linters
Migration commands: Match the detected migration tool exactly
Port numbers: Use framework defaults (3000 for Node, 8000 for Python, 8080 for Go)

二进制名称：使用
```
go.mod
```
、
```
package.json
```
或目录名称中的实际项目名称
源目录：使用实际的源目录（例如：
```
src/
```
、
```
app/
```
、
```
cmd/
```
）
开发服务器命令：匹配框架的开发服务器（例如：
```
next dev
```
、
```
uvicorn --reload
```
、
```
air
```
）
测试命令：匹配检测到的测试运行器
代码检查命令：匹配检测到的代码检查器
迁移命令：完全匹配检测到的迁移工具
端口号：使用框架默认值（Node为3000，Python为8000，Go为8080）

Mode A — Enhance Existing File

模式A — 增强现有文件

When

MODE = "enhance"

, do NOT replace the file from scratch. Instead, analyze it and improve it surgically.

当

MODE = "enhance"

时，不要从头替换文件。相反，分析文件并进行针对性改进。

5A.1 Analyze Existing File

5A.1 分析现有文件

Compare

EXISTING_CONTENT

against the

PROJECT_PROFILE

and best practices. Build a gap analysis:

Missing preamble/config — Check if the file has the recommended preamble:

Makefile:

SHELL := bash

.ONESHELL

.SHELLFLAGS

.DELETE_ON_ERROR

MAKEFLAGS

Taskfile:
```
version: '3'
```
,
```
output:
```
,
```
dotenv:
```
Justfile:
```
set shell
```
,
```
set dotenv-load
```
,
```
set export
```
Magefile:
```
//go:build mage
```
, proper imports

Missing standard targets — Check which of these are absent:

```
help
```
/
```
default
```
(self-documenting)
```
build
```
,
```
test
```
,
```
lint
```
,
```
clean
```
,
```
dev
```
,
```
fmt
```
```
ci
```
(aggregate target)

Missing project-specific targets — Based on

PROJECT_PROFILE

, check for:

Docker targets (if
```
has_docker
```
but no docker targets in file)
Database/migration targets (if
```
has_migrations
```
but no db targets)
Typecheck target (if TypeScript/mypy detected but no typecheck target)
Generate target (if code generation tools detected)
Coverage target (if test target exists but no coverage variant)

Quality issues — Check for anti-patterns from best practices:

Targets without descriptions/documentation
Missing
```
.PHONY
```
declarations (Makefile)
Hardcoded tool paths that should be variables
Missing version/commit detection
No self-documenting help target

将

EXISTING_CONTENT

与

PROJECT_PROFILE

和最佳实践进行比较。构建差距分析：

缺失的序言/配置 — 检查文件是否包含推荐的序言：

Makefile:

SHELL := bash

.ONESHELL

.SHELLFLAGS

.DELETE_ON_ERROR

MAKEFLAGS

Taskfile:
```
version: '3'
```
,
```
output:
```
,
```
dotenv:
```
Justfile:
```
set shell
```
,
```
set dotenv-load
```
,
```
set export
```
Magefile:
```
//go:build mage
```
, 正确的导入

缺失的标准目标 — 检查以下哪些目标不存在：

```
help
```
/
```
default
```
（自文档化）
```
build
```
,
```
test
```
,
```
lint
```
,
```
clean
```
,
```
dev
```
,
```
fmt
```
```
ci
```
（聚合目标）

缺失的项目特定目标 — 根据

PROJECT_PROFILE

，检查：

Docker目标（如果
```
has_docker
```
为真但文件中无Docker目标）
数据库/迁移目标（如果
```
has_migrations
```
为真但无数据库目标）
类型检查目标（如果检测到TypeScript/mypy但无类型检查目标）
生成目标（如果检测到代码生成工具）
覆盖率目标（如果存在测试目标但无覆盖率变体）

质量问题 — 检查最佳实践中的反模式：

无描述/文档的目标
缺失
```
.PHONY
```
声明（仅Makefile）
应使用变量但硬编码的工具路径
缺失版本/提交检测
无自文档化的help目标

5A.2 Plan Changes

5A.2 规划变更

Build a list of specific changes to make:

CHANGES = [
  { type: "add_preamble", detail: "Add .SHELLFLAGS and .DELETE_ON_ERROR" },
  { type: "add_target", name: "docker-build", detail: "Dockerfile detected but no docker target" },
  { type: "add_target", name: "help", detail: "No self-documenting help target" },
  { type: "fix_quality", detail: "Add ## comments to 3 targets missing descriptions" },
  { type: "add_variable", detail: "Add VERSION/COMMIT detection via git" },
  ...
]

构建具体变更列表：

CHANGES = [
  { type: "add_preamble", detail: "添加.SHELLFLAGS和.DELETE_ON_ERROR" },
  { type: "add_target", name: "docker-build", detail: "检测到Dockerfile但无Docker目标" },
  { type: "add_target", name: "help", detail: "无自文档化的help目标" },
  { type: "fix_quality", detail: "为3个缺失描述的目标添加##注释" },
  { type: "add_variable", detail: "通过git添加VERSION/COMMIT检测" },
  ...
]

5A.3 Apply Changes

5A.3 应用变更

Preserve the existing structure — Keep the user's ordering, naming, and style
Preserve existing targets exactly — Do NOT modify working targets unless fixing a clear bug or adding a missing description
Add new targets in the appropriate section — Follow the existing grouping pattern (if the file uses
```
##@
```
sections, add to matching section; if no sections, append logically)
Add missing preamble lines at the top, before existing content
Add missing variables near existing variable declarations
Use the template as reference for the syntax of new targets, but adapt to match the style already present in the file (e.g., if existing Makefile uses tabs + simple recipes, don't introduce complex multi-line scripts)

保留现有结构 — 保持用户的排序、命名和风格
完全保留现有目标 — 除非修复明显的错误或添加缺失的描述，否则不要修改正常工作的目标
在适当的部分添加新目标 — 遵循现有的分组模式（如果文件使用
```
##@
```
章节，添加到匹配的章节；如果无章节，逻辑上追加）
在顶部添加缺失的序言行，位于现有内容之前
在现有变量声明附近添加缺失的变量
使用模板作为新目标语法的参考，但调整以匹配文件中已有的风格（例如，如果现有Makefile使用制表符+简单脚本，不要引入复杂的多行脚本）

Quality Checks (Both Modes)

质量检查（两种模式）

Before writing the file, verify:

All targets have descriptions/documentation (## comments, desc:, [doc()], doc comments)
No hardcoded paths that should be variables
Package manager detection is correct
Self-documenting help target is included
```
.PHONY
```
declarations for all non-file targets (Makefile only)
Dangerous operations have confirmations (Justfile) or warnings

写入文件前，验证：

所有目标都有描述/文档（##注释、desc:、[doc()]、文档注释）
无应使用变量但硬编码的路径
包管理器检测正确
包含自文档化的help目标
所有非文件目标都有
```
.PHONY
```
声明（仅Makefile）
危险操作有确认（Justfile）或警告

Step 6: Write File & Report

步骤6：写入文件并报告

6.1 Write the File

6.1 写入文件

Mode B (Generate New):

Write the generated content using the

Write

tool:

Tool	Output Path
Makefile	`Makefile`
Taskfile	`Taskfile.yml`
Justfile	`justfile`
Magefile	`magefile.go`

Mode A (Enhance Existing):

Write the enhanced content to the same path where the existing file was found (preserving the original filename casing and location). The file is updated in-place — no need to ask about overwriting since we're improving, not replacing.

模式B（生成新文件）：

使用

Write

工具写入生成的内容：

工具	输出路径
Makefile	`Makefile`
Taskfile	`Taskfile.yml`
Justfile	`justfile`
Magefile	`magefile.go`

模式A（增强现有文件）：

将增强后的内容写入现有文件所在的路径（保留原始文件名的大小写和位置）。文件将就地更新——无需询问是否覆盖，因为我们是改进而非替换。

6.2 Display Summary

6.2 显示摘要

Display summary using format from

references/SUMMARY-FORMAT.md

. Shows targets table, project profile used, and quick start command for Mode B (generate), or what changed + new/existing targets for Mode A (enhance). Include installation hints if the tool requires setup.

使用

references/SUMMARY-FORMAT.md

中的格式显示摘要。对于模式B（生成），显示目标表、使用的项目概况和快速启动命令；对于模式A（增强），显示变更内容以及新增/现有目标。如果工具需要设置，包含安装提示。

Step 7: Project Documentation Integration

步骤7：项目文档集成

After writing the build file, integrate quick commands into project docs. For detailed integration procedures (README, AGENTS.md, existing markdown) → read

references/DOC-INTEGRATION.md

Brief: scan for existing command sections, update or append quick reference, suggest AGENTS.md creation if missing.

写入构建文件后，将快速命令集成到项目文档中。如需详细的集成流程（README、AGENTS.md、现有markdown）→ 阅读

references/DOC-INTEGRATION.md

简要说明：扫描现有命令章节，更新或追加快速参考，建议在缺失时创建AGENTS.md。

Artifact Ownership and Config Policy

工件所有权和配置策略

Primary ownership: generated or enhanced build automation files (
```
Makefile
```
,
```
Taskfile.yml
```
,
```
justfile
```
,
```
magefile.go
```
).
Allowed companion updates: quick command snippets in existing docs or
```
AGENTS.md
```
when directly tied to the generated build workflow.
Config policy: config-agnostic by design. This skill uses repository detection and fixed AI Factory context files rather than
```
config.yaml
```
.

主要所有权：生成或增强的构建自动化文件（
```
Makefile
```
、
```
Taskfile.yml
```
、
```
justfile
```
、
```
magefile.go
```
）。
允许的配套更新：与生成的构建工作流直接相关的现有文档或
```
AGENTS.md
```
中的快速命令片段。
配置策略：设计为与配置无关。本技能使用仓库检测和固定的AI Factory上下文文件，而非
```
config.yaml
```
。