team-setup

team-setup

概述

team-setup 是一项交互式技能，可引导你设置团队 AI 指令。它会提供四种模式，解释每种选项，确认你的选择，然后执行设置。

可通过两种方式调用：

• 用户调用（/team-setup）——可随时用于配置或检查项目。
• 由模型通过 team-boot 调用——当项目没有 .adlc/init-options.json 配置时，在会话开始时自动调用（自安装），让未配置的项目自行完成接入，用户无需知道该命令。

这项技能不会破坏现有内容：它绝不会覆盖现有文件或目录。如果目标路径中已包含已配置的团队 AI 指令，它会检测到这一点，并提供“已配置”模式。

何时使用

• 从头开始组建新团队，需要一个中立的团队 AI 指令脚手架，以便稍后填充。
• 团队已有 GitHub 指令仓库，你想在本地克隆。
• 你已有本地团队 AI 指令目录（例如来自之前的项目），并希望将其接入。
• 你不确定是否已配置团队 AI 指令，想快速检查。
• 项目尚未接入团队 AI 指令（没有 .adlc/init-options.json 中的 team_ai_directives 字段）。
• 会话开始时，team-boot 检测到项目未配置后自动调用（自安装）。

拒绝处理（由 team-boot 调用时）

当 team-boot 因项目尚未配置而调用此技能时，用户可能会选择暂时不设置团队 AI 指令。应明确处理拒绝，以避免重复提示循环：

• 如果用户在选择模式时拒绝，不要运行任何模式。正常退出，并告知 team-boot 用户已拒绝。
• 提供持久退出选项：“不再为此项目询问？” 如果用户选择是（仅限构建模式），则在 .adlc/init-options.json 中写入 team_ai_directives: null：

  echo '{"team_ai_directives": null}' > ".adlc/init-options.json"
  

  此标记会让 team-boot 在后续每次提示时静默跳过设置。
• 在计划/只读模式下，无法写入持久退出选项——拒绝仅对当前会话有效；告知 team-boot 延后处理。
• 绝不强制选择模式；设置的每一步都必须征得用户同意。

核心流程

目标

使用四种模式之一设置团队 AI 指令。

安全性：输入验证（所有模式）

执行任何模式之前，验证用户提供的每个值（路径、URL、团队名称）。这些值会插入 Shell 命令；未经验证的输入可能导致命令注入。

• 路径（{DEST}、{ABSOLUTE_PATH}）：如果包含 `、$、;、|、&、(、)、<、>、换行符或反斜杠，则拒绝。 使用前通过 realpath/Resolve-Path 将其解析为绝对路径。
• 团队名称：必须匹配 ^[A-Za-z0-9 ._-]+$。其他内容一律拒绝。
• 克隆 URL（模式 1）：必须以 https:// 开头。拒绝 file://、ssh:// 以及任何非 https 协议，除非用户明确确认风险。 克隆过程不会运行仓库中的代码，但之后 Agent 会读取克隆的内容——只克隆你信任的仓库。

如果任一值未通过验证，说明具体是哪个值以及原因，并重新询问。绝不要将用户输入插入 Python/eval 源字符串——应通过环境传递（参见模式 2）。

**快速路径：**如果 .adlc/init-options.json 已包含有效的 team_ai_directives 路径，则跳转至模式 4（已配置）——不要重新克隆、更改指向或重新搭建脚手架。

模式一览

#	模式	适用情况	详情见
1	从 GitHub 克隆	团队已有指令仓库	references/mode-clone.md
2	指向现有本地路径	指令目录已存在于本地	references/mode-local.md
3	搭建空白指令脚手架	从头开始组建团队	references/mode-scaffold.md
4	已配置	检查/验证现有接入	references/mode-configured.md

模式 1：从 GitHub 克隆

完整操作指南见 references/mode-clone.md。

模式 2：指定现有本地路径

完整操作指南见 references/mode-local.md。

模式 3：搭建新的空白团队 AI 指令

完整操作指南见 references/mode-scaffold.md。

模式 4：已完成配置

完整操作指南见 references/mode-configured.md。

模式选择流程

1. 探索：向用户提供四个选项：

   How would you like to set up team-ai-directives?
   
   1) Clone from GitHub — Clone an existing repository
   2) Point to existing local path — Use a team AI directives you already have
   3) Scaffold new empty team AI directives — Create a fresh neutral team AI directives
   4) Already configured — Check existing configuration
   

2. 说明：针对所选模式，解释将执行的操作并展示详细信息。

3. 确认：执行前请用户确认。

4. 写入/执行：执行所选模式的设置。

设置后配置

任何模式成功完成后，更新项目配置：

1. 将 team_ai_directives 写入 .adlc/init-options.json
2. 运行快速健康检查，确认可访问团队 AI 指令：
   • {TEAM_AI_DIRECTIVES}/context_modules/constitution.md 存在
   • {TEAM_AI_DIRECTIVES}/.skills.json 存在且为有效 JSON
3. 检查 .gitignore 约定（布局允许列表——见下方的 Gitignore 约定检查步骤）。
4. 注入项目级 AGENTS.md 指令——完整命令和受管理区段约定见 references/post-setup-agents.md。
5. 安装 MCP 配置——合并详情见 references/post-setup-mcp.md。

Gitignore 约定检查

确认 .gitignore 遵循 ADLC 允许列表——全新的 team setup 绝不能留下对整个 .adlc/ 的忽略规则（这会隐藏团队模型所依赖的已跟踪 .adlc/ 产物）：

1. 如果 .gitignore 中包含单独的 .adlc/ 规则，请将其（以及任何与之冲突的 .adlc/* + !.adlc/... 行）替换为 R7 允许列表： 忽略 .adlc/*、.adlc/evals/results/、.adlc/memory/*、 .adlc/team-learn-report.md、.adlc/team-levelup-report.md 和 graphify-out/，同时重新纳入 !.adlc/init-options.json、 !.adlc/workspace.yml、!.adlc/drafts/、!.adlc/evals/、 !.adlc/memory/、!.adlc/memory/evals/ 和 !.adlc/memory/evals/holdout.json。规范规则列表位于 工作区技能的 scripts/bash/paths.sh（GITIGNORE_RULES_ALLOWLIST， 在 scripts/powershell/paths.ps1 中有对应副本）。
2. 另请确认已忽略 Agent 安装路径规则（.agents/、 .opencode/、.claude/、.cursor/、.codex/、.gemini/、 .qwen/、.devin/、.tabnine/、skills-lock.json、 .skills.json、.mcp.json、.events.json、.pytest_cache/、 .ruff_cache/）。
3. 绝不删除无关（非 ADLC）规则；只添加缺失的允许列表规则。
4. 已跟踪的旧版文件仍可正常工作——允许列表只对未跟踪文件生效，因此切换前无需迁移。

常见的自我说服

自我说服	错误之处	应采取的做法
“我手动克隆就行。”	手动克隆会跳过 .adlc/init-options.json 配置，因此 Agent 找不到团队 AI 指令。	使用模式 1——该模式会克隆并完成配置。
“我已经有团队 AI 指令目录了，直接用就行。”	该目录可能不完整（缺少必需文件），或尚未接入配置。	使用模式 2——该模式会验证目录结构并创建配置项。
“我手动创建几个文件就行。”	搭建不完整会导致健康检查和 Agent 发现功能失效。	使用模式 3——该模式会创建所有 10 个必需文件，并确保结构有效。
“我确定已经配置好了。”	路径可能已过期或已移动，或者环境变量可能指向已删除的目录。	使用模式 4——该模式会验证现有配置。
“不提供团队名称也没关系。”	团队名称会用于 README.md——名称留空会使团队 AI 指令匿名，更难审计。	使用模式 3 时务必提供团队名称。

风险信号

• 克隆到已有目录 — 模式 1 会在目标已存在时拒绝操作，以防覆盖。
• 指定不存在的路径 — 模式 2 会在继续操作前验证路径是否存在。
• 在必需目录不可写时搭建脚手架 — 模式 3 会使用 mkdir -p 创建目录，但遇到权限错误时会失败；请先检查权限。
• 跳过 team_ai_directives 配置写入 — 如果 init-options.json 中没有此字段，Agent 就无法发现团队 AI 指令。
• 在 init-options.json 中使用相对路径 — 始终解析为绝对路径，这样配置才能在不同工作目录中通用。
• 在模式 3 中跳过 git init — 未初始化 git 的团队 AI 指令脚手架无法用于 /team-levelup（分支/提交/PR 工作流）。模式 3 会自动运行 git init；如果跳过了，请在运行 /team-levelup 之前手动运行 git init。
• 跳过项目级 AGENTS.md 注入 — 如果项目的 AGENTS.md 中没有 managed section，不支持事件的 Agent 就没有会话启动指令来加载团队上下文。仅配置 .adlc/init-options.json 并不足够——它会告诉技能团队 AI 指令的位置，但没有任何内容会告知 Agent 进行检查。（对于支持事件的 Agent，会话启动钩子无论如何都会注入引导信息，但 AGENTS.md 仍是后备方案，也是“正在使用的团队上下文”输出约定的来源。）
• 将用户输入插入 Python/ shell 源字符串 — 应通过环境（os.environ）传递路径；将 $ABSOLUTE_PATH 插入 Python 单行命令是命令注入漏洞。
• 在模式 1 中克隆非 https:// URL — 拒绝 file:///ssh:///其他方案；Agent 之后会读取克隆的内容，因此只能克隆可信仓库。
• 跳过 MCP 配置安装 — .mcp.json 中的服务将保持未配置状态；项目将无法访问团队声明的 MCP 服务。
• 接受路径或团队名称中的 Shell 元字符 — 在将它们插入 mkdir/git commit/heredocs 之前进行验证（参见输入验证）。
• 将用户拒绝视为错误 — 拒绝设置是有效结果；正常退出，告知 team-boot 用户已拒绝，并提供 team_ai_directives: null 作为选择退出标记（仅限构建模式）。
• 在计划/只读模式下写入选择退出标记 — 持久化选择退出需要写入；在计划模式下，拒绝仅对当前会话有效，设置会延后。

验证

• 团队 AI 指令目录存在于配置的路径。
• {TEAM_AI_DIRECTIVES}/context_modules/constitution.md 存在。
• {TEAM_AI_DIRECTIVES}/context_modules/rules/ 存在。
• {TEAM_AI_DIRECTIVES}/context_modules/personas/ 存在。
• {TEAM_AI_DIRECTIVES}/context_modules/examples/ 存在。
• {TEAM_AI_DIRECTIVES}/CDR.md 存在。
• {TEAM_AI_DIRECTIVES}/.skills.json 存在且为有效 JSON。
• .adlc/init-options.json 包含带有绝对路径的 team_ai_directives 字段。
• .gitignore 遵循布局允许列表（不得整体忽略 .adlc/；需包含跟踪例外 !.adlc/init-options.json、!.adlc/workspace.yml、!.adlc/drafts/、!.adlc/evals/、!.adlc/memory/evals/holdout.json）。
• 项目级 AGENTS.md 存在，且包含 `` 管理区段，其中包含事件钩子注意事项、备用 team-boot 调用方式，以及 Team Context in Use 输出约定。
• （仅限模式 3）在 {TEAM_AI_DIRECTIVES} 内运行 git rev-parse --is-inside-work-tree 成功。
• 运行 team-verify（team-repair 的阶段 0）通过全部 7 项检查。
• 所有用户提供的路径／URL／团队名称均通过输入验证（不含 shell 元字符；克隆 URL 使用 https://）。
• 模式 2 通过环境变量写入了 team_ai_directives（没有将 $ABSOLUTE_PATH 插值到 Python 源代码中）。
• 如果 {TEAM_AI_DIRECTIVES}/.mcp.json 存在，其中声明的任何 mcpServers 均已成功合并到项目配置中，并已标明未解析的环境变量。
• （由 team-boot 调用的模型）用户拒绝后已干净退出，且未运行任何模式；已提供持久退出选项，并且仅在构建模式下写入了 team_ai_directives: null。

配置

• TEAM_AI_DIRECTIVES — 团队 AI 指令的路径（覆盖 .adlc/init-options.json）。
• .adlc/init-options.json — 项目级配置文件，包含 team_ai_directives 字段。
• 默认回退：相对于项目根目录的 team-ai-directives/。
• team-helpers.sh / team-helpers.ps1 — 用于搭建脚手架和解析路径的共享脚本。

12-Factor 对齐

Factor XI（指令即代码）——建立一个受版本控制的团队指令仓库。