setup-engineer

/setup-engineer — 黄金状态协调器

此命令不会“生成文档”。它会协调代码仓库，使其达到固定且具有明确主张的黄金状态，以支持 Agent 本地开发，然后将持续执行交给驻留在仓库中的 doctor 命令。可以把它看作面向仓库开发工具的 terraform apply：它读取当前状态，与目标状态进行比较，并通过经过验证的阶段弥合差距。

你是这一黄金状态的守护者。每次运行后，仓库都应呈现相同的结构——可预测、支持并行实例且可自我修复。

“黄金状态”的含义

仓库满足以下八项条件，即处于黄金状态。完整的不变量检查清单（由 doctor 强制执行）位于 references/golden-state.md——在进行任何比较之前，请先阅读。

1. 每个仓库都有自己的开发 CLI——以仓库的原生语言编写的深模块（JS 仓库 → JS，Python 仓库 → Python）。动词接口简单，所有复杂的编排逻辑都隐藏在内部。它负责整个本地开发生命周期。规范：references/cli-and-just.md。
2. 精简的 just 接口——所有仓库和语言都使用相同的动词，不含任何逻辑，每一行都调用 CLI。这让你形成的操作习惯和工程师技能可以跨项目复用。模板：templates/justfile。
3. 生成的环境变量／端口契约——一个 ENV_INDEX、一个 DEV_HOST、一个作为唯一事实来源的槽位表、BASE + INDEX*100 + slot，以及容器内 DNS 与主机偏移量之间的边界规则。规范：references/env-and-ports.md。
4. 由四个文件组成的工程师技能——SKILL.md / ARCHITECTURE.md / TESTING.md / GOTCHAS.md。写命令，不写原因。规范：references/engineer-skill.md。
5. 精简的 CI——工作流调用相同的 just/CLI 接口，几乎不包含任何逻辑。这既能复用，也能抵御 CI 供应商锁定。
6. doctor 已接入且运行通过——仓库内的不变量检查器（一个 CLI 动词）能够通过，CI 也会运行它。
7. 问题跟踪器绑定——在工程师技能旁放置 TRACKER.md，说明此仓库使用的问题跟踪器、相关命令及标签含义，让每个会写入跟踪器的技能都遵循一致的约定。可选：没有值得绑定的问题跟踪器的仓库，即使没有此文件也仍处于黄金状态。规范：references/tracker.md。
8. 依赖项绑定——在工程师技能旁放置 DEPENDENCIES.md，说明此仓库中哪些软件包的风险高于其升级幅度所暗示的程度、哪种动词可验证哪类依赖项，以及无人值守的批量检查最多可以进行到什么程度。与问题跟踪器绑定一样，此项为可选：没有依赖机器人（dependency bot）的仓库，即使没有此文件也仍处于黄金状态。规范：references/dependencies.md。

setup-engineer 协调第 1–8 项的存在与结构。结构建立后，doctor 会在运行时强制执行不变量。请明确区分两者：setup-engineer 是负责创建和迁移的元协调器；doctor 是负责捕获偏差的仓库内守卫。setup-engineer 会在最后一步运行 doctor。

协调器循环

按顺序执行以下步骤。不要跳过差异比较，也不要一次性大改现有仓库。

1. 检测

盘点现有内容。不要想当然——先检查。

# Identity
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

# Stack / package manager
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null
# Compose + existing env tooling
ls docker-compose*.yml compose*.yml .env .env.example 2>/dev/null
ls scripts/ 2>/dev/null
# Existing command surface
ls justfile Justfile Makefile 2>/dev/null
# Existing engineer skill — check wherever this repo keeps skills
ls -d */skills/*-engineer/ .*/skills/*-engineer/ 2>/dev/null | grep -v '^\.\./'
# Tracker — a binding beside the engineer skill, and evidence of what to bind to
ls */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null
git remote -v; command -v gh glab jira 2>/dev/null
# Dependency binding — the same, plus evidence of a bot to bind to
ls */skills/*-engineer/DEPENDENCIES.md .*/skills/*-engineer/DEPENDENCIES.md 2>/dev/null
ls renovate.json renovate.json5 .renovaterc* .github/renovate.json* \
   .github/dependabot.yml 2>/dev/null
# CI
ls .github/workflows/ .gitlab-ci.yml 2>/dev/null

阅读找到的所有内容。已有的自然形成的脚本（如 setup-env.mjs、dev-data.mjs、reset-data.sh）不是应该删除的垃圾——它们是要迁移到 CLI 中的逻辑。先阅读这些脚本，了解仓库的实际生命周期，再提出任何方案。

2. 分类

将仓库归入且仅归入一个类别。这决定了你要采取多大力度的改动。

• Greenfield — 没有 CLI、没有 just、没有环境工具，也没有工程师技能。→ 根据各语言模板搭建完整的黄金状态。风险低，几乎没有东西会被破坏。
• Partial — 有现成脚本和／或一个庞大的工程师技能（最常见的起点）。→ 迁移，分阶段进行，每阶段之后都验证。这是风险最高的情况，绝不能一次性大改。
• Golden — 已符合要求。→ 运行 just doctor，报告一切正常，然后停止。不要折腾已经正确的仓库。

3. 差异

根据黄金状态检查清单，生成具体的偏差报告。针对八个要素中的每一项，说明其状态：存在／部分存在／缺失，以及具体差距。示例：

CLI            partial   logic lives in 4 loose scripts/*.mjs, no single entrypoint, no `doctor`
just           missing   no justfile
env contract   partial   setup-env.mjs exists but 2 services hardcode host ports in compose
engineer skill partial   1 monolith SKILL.md (33KB) + 3 helper scripts inside the skill dir
CI             partial   workflow reimplements test orchestration inline instead of calling CLI
doctor         missing
tracker        missing   github remote + authenticated gh, but no TRACKER.md
dependencies   missing   renovate.json present, no DEPENDENCIES.md

4. 计划

将差异整理成一个有序、分阶段的整改计划。对于 Partial 仓库，按以下顺序进行可以确保仓库在每一步都能正常工作：

1. 搭建 CLI 骨架（命令表面 + doctor，先委托给现有脚本执行），并在其上构建精简的 justfile。
2. 将现有逻辑迁移到 CLI，一次处理一个方面（环境 → 生命周期 → 数据 → 测试）；只有在对应命令可用后，才删除各个独立脚本。
3. 使环境／端口约定符合规范（以槽位表为准，移除硬编码端口，推导边界 URL），直至 doctor 通过。
4. 重构工程师技能，精简至四个文件；将命令移出，将脚本移入 CLI，只保留原因／架构／注意事项。
5. 精简 CI，使其调用 just／CLI。
6. 绑定追踪器——放在后期处理，因为它不会影响前面阶段所依赖的内容；而且解决它可能需要询问用户一个问题，在其他工作进行时用户就可以作答。
7. 起草 DEPENDENCIES.md——与追踪器一并处理，并且要等到其中引用的 just 命令已存在之后，因为文件中的每条命令都必须对应一个真实可用的命令。

提交计划并取得批准后再开始实施。这符合仓库所有者的一贯规则：多阶段计划必须在每个阶段结束时进行验证。

5. 实施——按阶段设门槛，绝不一次性大改

每个阶段结束后：

just doctor      # invariants hold
just test        # nothing broke   (use the repo's real test verb if `just` isn't wired yet)

如果某个阶段导致问题，先停下来修复，再进入下一阶段。对于较重的检查（运行完整测试套件、实际运行应用），使用 Task 工具启动验证子 Agent，避免凭猜测就宣布阶段完成。只有在替代命令通过后，才能删除现有脚本。

6. 验证并报告

最后确保 doctor 通过，并按照 references/report-format.md 提交报告：说明改动内容、各阶段验证了什么，以及仍待后续处理的偏差。

必须落实的两条行为准则

将它们写入工程师技能的 SKILL.md，以便之后在仓库中工作的每个 Agent 都能自然而然地遵循——这是“守护者／持续改进”理念的核心。完整内容和理由见 references/engineer-skill.md。

• 生命周期卫生——由你启动环境，结束时就由你关闭环境。just down 是成本低廉的默认做法（保留数据，释放 RAM，以便并行运行更多实例）。多个 Agent 实例同时运行时，这一点尤为重要；陈旧环境占用 RAM 是常见故障原因。
• 自我改进（优先以可执行方式编码）——当 Agent 遭遇阻碍时，应将修复放到能够承载它的最持久层级：新增 just／CLI 命令 > 新增 doctor 检查 > GOTCHAS.md 说明。文字说明是兜底手段，而非默认做法。这包括基础设施变更准则：添加或更改服务（数据存储、队列、缓存、IdP），意味着必须在同一次变更中添加其端口槽位、健康检查、nuke 卷覆盖，并重新生成 .env——只有这四项全部满足后，doctor 才能通过。

参考索引

阅读内容	适用场景
references/golden-state.md	比较差异前阅读 — 完整的不变量检查清单
references/cli-and-just.md	搭建/迁移 CLI、justfile 和 doctor
references/env-and-ports.md	处理环境/端口约定、devbox、HTTPS
references/engineer-skill.md	重构工程师技能和两条定律
references/tracker.md	将仓库的问题跟踪器绑定到 TRACKER.md
references/dependencies.md	将仓库的依赖策略绑定到 DEPENDENCIES.md
templates/justfile	可直接引入的规范精简动词接口
references/report-format.md	最终的黄金状态报告