sdd-new-session

Nova sessão de trabalho (new-session)

Na primeira resposta desta skill, comece com esta linha, uma única vez: sdd-new-session v1.3.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Um comando, uma tarefa, um diretório: git worktree + uma nova branch criada a partir do estado remoto atual da branch de produção, pronta para abrir no editor.

如何与学生交流

使用此 skill 的人通常从未用过 git。每条回复都是对一个步骤的说明，而不是技术报告。

4 个步骤始终使用以下名称：

步骤	面向学生的名称	此 skill 中的步骤
1	预检	步骤 0（只读取）
2	了解仓库	步骤 1 — 仅第一次执行；如果已写入 sdd/ambiente.md，则跳过 ➖
3	创建工作分支	步骤 2，项目 1 至 5
4	在编辑器中打开	步骤 2，项目 6，以及步骤 3

每条回复都按以下顺序包含这些部分（没有内容的部分可跳过）：

1. 状态 — 一行：✅ 1 预检 · ➖ 2 了解仓库 · ▶️ 3 创建工作分支 · ⬜ 4 在编辑器中打开 （✅ 已完成 — 不只是访问过；▶️ 当前步骤；⬜ 待处理；⏸️ 暂停；➖ 跳过）。返回某个步骤时，将原因写在 现在 中。
2. 已完成的内容 — 用简短句子说明上一步的结果，不要贴命令输出。预检正常时，不要粘贴 checar.sh 中 ✅ 那一行：将其内容转述成这些句子。记录学生的选择："你回答了是：……"。
3. 现在：步骤 N — 名称 — 用 2 至 4 句话说明此步骤的作用和原因，让从未见过终端的人也能明白。如果要创建内容，用编号步骤说明将要做什么，以及不会发生什么（不会有任何内容上传到互联网；不会修改你的任何文件）。执行耗时操作（安装依赖项）之前，用一句话说明将运行什么，并告诉学生无需回复。
4. 你的决定 — 仅在此 skill 已经提问的地方出现：是否选择不使用 git 的项目、所选名称已存在时的新名称，以及有多个文件夹时哪个文件夹是项目。授权请求：问题用粗体显示，并列出选项及各自的结果；开放式问题：问题用粗体显示，并说明如何回答，同时提供“我不知道”选项；组合问题应编号，回答时可以对应编号。回答与选项不符 ⇒ 先解答疑问，再重复列出选项。能自行查明的，就自行查明 — 不要提问。
5. 下一步 — 用一行说明收到回答后会发生什么。

语言规则：

• 每条回复只处理一个步骤。以决定部分结束并停止：不要接着进入下一步。
• 技术词首次出现时必须附带解释 — 状态中的术语也不例外：
  • git — “项目的版本历史记录（git）”；
  • commit — “已保存的一个版本（commit）”；
  • frente — “一个仅用于此任务的独立文件夹（工作分支，也称 worktree），避免与项目中已有内容混在一起”；
  • branch — “此任务的版本线（branch），从当前用于生产的版本创建”；
  • remoto / origin — “GitHub 上的项目副本”；
  • pré-voo — “创建任何内容之前，确认文件夹和 GitHub 副本都已就绪”；
  • dependências — “可以通过一个命令重新安装的辅助程序”；
  • cenário — “此项目进入生产环境的方式：直接发布、通过审核（pull request），或使用受支持的版本”。 不要提 refspec、HEAD、孤立的 worktree 或 ls-remote：只说明其作用。
• 不要原样转发命令输出 — checar.sh 的报告也不例外。请转述：有多少项、哪些内容（最多 10 项，其余写“另有 N 项”）、哪些内容值得关注。只有在学生需要运行命令时才显示命令 — 并用编号步骤列出，每步一个命令，同时说明屏幕上会显示什么。
• 不要引用或概述此 skill 或其他 skill 的指示（“skill 要求……”“根据步骤 0……”）。应说明学生能理解的原因："没有 GitHub 副本，工作分支就无从创建。"。
• 暂停也要给出步骤。 当某个步骤无法继续时，状态使用 ⏸️，用一句话说明原因、指出要在哪里操作（终端、编辑器、Finder、浏览器），列出编号步骤并说明每一步会看到什么，说明尚未完成的事项（"尚未创建任何工作分支。"）；如果学生需要采取行动，还要说："完成后，请再联系我 — 我会从这里继续。"。预检中每种发现的对应解释见步骤 0 的表格。

连接远程服务的每条命令规则

fetch、push、pull、ls-remote 和 remote show 都会在不询问密码的情况下运行：在 bash/zsh 中运行 GIT_TERMINAL_PROMPT=0 git …；在 PowerShell 中运行 $env:GIT_TERMINAL_PROMPT=0; git …。如果不这样做，需要登录的远程服务会让 git 在终端中询问密码，而你只能等待用户看不到的回复。如果上述命令之一一直没有反应，请检查编辑器（VS Code、Cursor）是否打开了 GitHub 登录窗口——这是合法的登录方式，不会被关闭。向用户只展示当前使用的 shell 对应形式。

步骤 0 — 确认你能否执行此操作

运行 git --version。有 3 种不同情况，需要分别处理：

• 工具无法执行任何命令（你在聊天应用中，无法访问用户的计算机）：停止，并准确地说："我无法访问你的仓库——我运行在应用中，而不是你的计算机上。要完成这项任务，你需要在终端中安装 Claude Code 或 Codex，并在项目文件夹中打开它。" 接着说明你所用 Agent 当前的安装命令，以及官方文档所在位置。
• 命令可以执行，但 git 不存在（git: command not found；在 PowerShell 中则是 CommandNotFoundException 或 'git' is not recognized）：停止，并说 "这台计算机上没有安装 git。"，附上链接 https://git-scm.com/downloads，并说明安装后需要关闭终端再重新打开。最后说 "没有创建任何内容。安装后，请重新提出该请求。" 不要说你在聊天应用中：你是在终端中。
• git 存在：继续进行预检。预检要先于其他所有操作，因为它也会在文件夹不是仓库时给出答复，并说明具体是哪种情况（云同步文件夹、个人文件夹、项目位于子文件夹中、空文件夹、没有 git 的项目）。绝不要只回答 "git init"。

预检。 确认 git 已就绪后，在创建任何内容（包括 sdd/ambiente.md）之前，检查文件夹的位置，以及前端能否从远程服务创建：

• 如果与此技能位于同一技能目录（.claude/skills/、 .agents/skills/ 或 Agent 的全局目录）中存在 sdd-checar-ambiente 技能，且有 bash，请运行 bash <技能目录>/sdd-checar-ambiente/scripts/checar.sh --frente，并阅读输出——它不会转发给学员：每项发现都对应下方 如何翻译每项发现 表格中的译文。 退出代码为 1（🔴 Impede o trabalho 区块）⇒ 到此为止，按表格回复——如果发现是 “此项目尚未使用 git”，另请参阅下方的 没有 git 的项目。退出代码为 0 ⇒ 唯一一行是 ✅ Pronto para abrir a frente: …；继续（其内容将成为第 1 步的“已完成事项”）。退出代码为 0 但没有这一行（而是完整报告，其中含 ⚠️ 或 ✅ Repo …）？安装的 sdd-checar-ambiente 早于 1.1.0，不认识 --frente：不要将其算作预检——请手动完成下方的检查，并建议更新该技能。 如果输出含 “终端可能是在错误的文件夹中打开的” ⇒ 安装的 sdd-checar-ambiente 早于 1.2.0，无法判断具体情况：请手动完成下方的检查 0 和 A–D，并建议更新该技能。
• 没有该技能或没有 bash（仅 PowerShell）时，请按以下顺序手动进行相同检查，遇到首个失败项即停止： 0. 同步文件夹（最先检查，无论是否有仓库）：路径（bash/zsh 中为 pwd -P， PowerShell 中为 (Get-Location).Path）包含 Library/Mobile Documents、Library/CloudStorage、 iCloudDrive、OneDrive、Dropbox、Google Drive、My Drive 或 Meu Drive；或者在 Mac 上，文件夹位于 ~/Desktop 或 ~/Documents，且 ls -ld ~/Library/Mobile\ Documents/com~apple~CloudDocs/Documents（或 Desktop）显示为快捷方式（->）——这表示“桌面”和“文稿”位于 iCloud 中，路径不会改变。 ⇒ “此文件夹位于 <服务商> 中，它会同步所有变更——.git 和工作分支可能损坏或重复。”：通过 Finder 或文件资源管理器将项目移出云端（例如 ~/Projetos），并在那里打开终端。 如果 git rev-parse --show-toplevel 失败，请按以下顺序说明具体属于哪种情况：
  • A. 个人文件夹——当前文件夹是 ~（$HOME；PowerShell 中为 $env:USERPROFILE）⇒ “终端位于你的个人文件夹中，而不是项目文件夹中。”（不要扫描个人文件夹）。
  • B. Git 仓库位于子文件夹中——bash/zsh： find . -mindepth 1 -maxdepth 3 \( -name node_modules -o -name .Trash -o -name Library \) -prune -o -name .git -print； PowerShell：Get-ChildItem -Recurse -Depth 2 -Force -Filter .git -ErrorAction SilentlyContinue | Where-Object { $_.FullName -notmatch 'node_modules' } | ForEach-Object { Split-Path $_.FullName -Parent }。 只有一个文件夹 ⇒ “项目位于 ./X——终端打开的位置比项目高一层。”：在该文件夹中重新打开聊天。 有两个或三个 ⇒ 列出并询问是哪一个。超过三个 ⇒ 说明数量并询问哪个是项目，不要全部列出。
  • C. 空文件夹——除 .DS_Store、desktop.ini、Thumbs.db 外没有其他内容（ls -A；PowerShell 中为 Get-ChildItem -Force）⇒ “此文件夹中还没有项目。”：从 sdd-brainstorm 技能开始；有内容需要保存时再加入 git。
  • D. 没有 git 的文件⇒ “此项目尚未使用 git——工作分支源于 git。”：参阅下方的 没有 git 的项目。 有仓库时：
  1. git remote 为空 ⇒ “仓库没有远程端——工作分支源于远程端。”，并运行 git remote add origin <仓库 URL>。有远程端，但没有名为 origin 的远程端（例如只有 upstream 的 fork）⇒ “仓库有远程端，但没有名为 origin 的远程端——工作分支源于 origin。”，并运行 git remote rename <名称> origin（或 git remote add origin <URL>）。这不是登录问题。
  2. 如果配置了编辑器登录窗口（已设置 GIT_ASKPASS 或 SSH_ASKPASS，或 git config core.askPass 非空——VS Code 或 Cursor 终端），先进行诊断：执行相同查询，但不使用该窗口和已保存的凭据，不会向任何人请求任何内容，最长等待 10 秒—— GIT_TERMINAL_PROMPT=0 GIT_ASKPASS= GCM_INTERACTIVE=never GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=8" git -c credential.helper= -c core.askPass= ls-remote --heads origin （PowerShell：$a=$env:GIT_ASKPASS; try { $env:GIT_TERMINAL_PROMPT=0; $env:GIT_ASKPASS=''; $env:GCM_INTERACTIVE='never'; git -c credential.helper= -c core.askPass= ls-remote --heads origin } finally { $env:GIT_ASKPASS=$a }）。 卡住或出现网络错误 ⇒ 是网络问题，不是窗口问题：定义了 GIT_ASKPASS 并不能证明已登录（网络中断时，git 根本不会请求密码）。任何其他响应 ⇒ 远程端已响应；继续。 然后（或直接执行，如果没有 GIT_ASKPASS），进行实际查询，并启用编辑器窗口（通过该窗口登录的用户可以通过验证）：GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=8" git ls-remote --heads origin （只有未配置专用 ssh 时才使用 GIT_SSH_COMMAND——GIT_SSH_COMMAND、GIT_SSH 或 core.sshCommand；使用该设置后，ssh 不会卡住并等待密码短语或主机确认）（PowerShell： $env:GIT_TERMINAL_PROMPT=0; $env:GCM_INTERACTIVE='never'; git ls-remote --heads origin—— GCM_INTERACTIVE 会阻止 Windows 凭据管理器窗口弹出，但不会禁用已保存的凭据）——如果超过 10 秒仍无响应，请中断。如果诊断曾请求登录后卡住（could not read Username、 terminal prompts disabled、Permission denied (）⇒ “编辑器的登录窗口正在等待响应。”：在窗口中回复，或运行 gh auth login，以免依赖该窗口；在任何其他情况下卡住 ⇒ 网络问题。登录错误（could not read Username、Authentication failed、 Permission denied (publickey)、Repository not found）⇒ “GitHub 不允许此计算机读取该仓库：要么地址错误，要么该仓库是私有的，而此计算机尚未登录 GitHub。”，并运行 gh auth login（同一行中的其他选项：SSH 密钥或 git 凭据管理器）；远程端不在 GitHub 上 ⇒ “远程端 <host> 拒绝了此计算机的访问（登录或权限问题）。”，使用该服务的登录方式——绝不要运行 gh auth login。Host key verification failed ⇒ 运行 ssh -T git@<host> 并回复 yes——这不是登录问题。 Could not resolve host、timed out，或无法确认是请求登录后卡住 ⇒ 没有互联网连接或网络被阻止（不要提密码）。其他任何消息 ⇒ 使用下方表格中的“其他发现”对应行：“我无法读取 GitHub 上的项目副本，原因无法识别。”，并运行 git remote -v——不要猜测原因，也不要向学员显示错误行。
  3. 没有列出任何分支 ⇒ “远程仓库还没有任何提交——工作分支源于该仓库。”，创建首次提交并运行 GIT_TERMINAL_PROMPT=0 git push -u origin <当前分支>。 任何阻塞项都会导致第 1 步暂停（状态为 ⏸️），并按下表翻译：以 “尚未创建任何工作分支。” 结尾；如果学员需要采取操作，还要加上 “完成后，请再次告诉我——我会从这里继续。”
• 没有 git 的项目（发现 D，或 checar.sh 返回相同文本）。此技能不会提交或发布，而未经检查就将项目加入 git，可能会把客户表格、.env 和 A1 证书传到 GitHub。因此：
  • 如果与此技能位于同一技能目录中存在 sdd-iniciar-repo 技能，回复应遵循 如何与学员沟通 的格式（第 1 步状态为 ⏸️、“已完成事项”和一句话的“现在”），不含 🔴 区块，不含 “解决后，请再次请求工作分支”（你自己会解决），也不要提及或解释此说明；请按以下两个选项做出决定：

    此项目尚未使用 git——工作分支源于 git。

    你想让我现在将此项目放入 git 和私有 GitHub 仓库中吗？我会先检查不能上传的内容，并在每个步骤征求你的同意。

    • 是——我会从头开始遵循 sdd-iniciar-repo（该技能会在每个步骤征求你的同意），完成后回到这里并创建工作分支。
    • 否——我会到此为止；不会创建或更改任何内容。 同意后，请从头执行 sdd-iniciar-repo；完成后，返回预检并创建前线。不同意则停止，并回复 "未创建任何前线。"

  • 如果不存在，请说明 skill sdd-iniciar-repo 可以完成这项工作，并且可通过 npx skills add robertodiasduarte/sdd-starter -a <claude-code 或 codex> -g -y 安装；然后只需提出请求： "使用 skill sdd-iniciar-repo 将此项目纳入 git。" 回复 "未创建任何内容。" 在尚未上传到 GitHub 的项目中，没有远程地址的仓库（第 1 项）也属于同一种情况：sdd-iniciar-repo 会从上次中断处继续。
• 预检正常时，不要生成报告：将 ✅ 行的内容写入“已完成的工作”，然后继续执行第 1 步。

如何翻译每项发现（来自 checar.sh --frente 或手动检查）。学生会收到“告诉学生”的内容、位置、步骤和结束语——绝不会收到脚本报告或 git 错误行：

发现项（脚本或检查如何识别）	告诉学员	位置	步骤（每步一条命令，并说明预期结果）	以什么结束
同步文件夹（“此文件夹位于 … 内”）	此文件夹由云端（）同步，而项目历史记录在这里会损坏。	Finder / 文件资源管理器	1. 将项目文件夹移出云端，例如移到 ~/Projetos（它会从云端消失，并出现在那里）。 2. 在新文件夹中打开终端。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
A. 个人文件夹（“终端位于你的个人文件夹中…”）	终端打开在你的个人文件夹中，而不是项目文件夹中。	终端 / 编辑器	1. 在项目文件夹中重新打开聊天。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
B. 一个子文件夹含 .git（“项目位于 ./X…”）	项目位于 X 文件夹中，比终端打开的位置深一层。	终端 / 编辑器	1. 在 X 中重新打开聊天。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
B. 两个或三个子文件夹（“子文件夹中有 git 仓库…”）	这里面有多个项目；我需要知道哪个是你的项目。	—	—	由你决定（授权）：“哪个文件夹是你的项目？”——每个文件夹提供一个选项：“X——我会告诉你如何在那里打开聊天。”
B. 多于三个（“这里面有 N 个含 git 的文件夹…”）	这里面有 N 个项目文件夹；我需要知道哪个是你的项目。	—	—	由你决定（开放式提问）：“你的项目在哪个文件夹中？请回复文件夹名称。”
C. 空文件夹（“此文件夹中还没有项目。”）	此文件夹为空：还没有项目可以开启工作线。	—	1. 从 skill sdd-brainstorm 开始；等有内容需要保存时再使用 git。	尚未创建任何工作线。
D. 项目未使用 git（“此项目还没有使用 git…”）	此项目还没有使用 git——而工作线始于 git。	安装了 sdd-iniciar-repo 时：—；未安装时：终端	已安装 sdd-iniciar-repo：显示 项目未使用 git 区块中的选项（是 / 否）。未安装时：1. npx skills add robertodiasduarte/sdd-starter -a <claude-code ou codex> -g -y（会请求确认并列出已安装的 skills）。 2. 关闭并重新打开 Agent。 3. 请求 “使用 skill sdd-iniciar-repo 将此项目纳入 git”（它会先检查文件夹中的内容）。	有选项时：等待决定。没有选项时：尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
Git 未设置姓名或邮箱（今天 --frente 不会产生此发现；这是普通模式下 checar.sh 的发现项）	git 还不知道你是谁；没有这些信息，首次保存版本会失败。	终端	1. git config --global user.name "Seu Nome"（不会显示任何内容）。 2. git config --global user.email "[email protected]"（不会显示任何内容）。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
没有远程仓库（“仓库没有远程仓库…”，第 1 项）	此项目还没有 GitHub 副本——而工作线始于这个副本。	终端（有选项时为 —）	项目尚未连接 GitHub，且已安装 sdd-iniciar-repo：显示相同的“是 / 否”选项（它会从项目停下的地方继续）。项目尚未连接 GitHub，且未安装 sdd-iniciar-repo：执行 D 行中的 3 个安装步骤。GitHub 上已有仓库：1. git remote add origin <endereço do repositório>（不会显示任何内容）。	有选项时：等待决定。否则：尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
远程仓库没有 origin（“…没有名为 origin 的远程仓库…”，第 1 项）	项目有远程副本，但名称不同；工作线要求它的名称为 origin。	终端	1. git remote rename <nome> origin（不会显示任何内容）。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
凭据被拒绝（“GitHub 不允许此计算机读取仓库…”）	GitHub 不允许此计算机读取仓库：要么地址错误，要么仓库是私有的且此计算机尚未登录。	终端和浏览器	1. gh auth login（会打开浏览器；使用 GitHub 帐户登录，然后返回终端）。 2. 再次请求创建工作线。非 GitHub 远程仓库：登录相应服务。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
尚未确认服务器（Host key verification failed）	此计算机从未确认过服务器身份；这不是密码问题。	终端和浏览器	1. ssh -T git@<host>（它会显示服务器指纹并询问你是否信任）。 2. 在 GitHub 上，回答之前，请在 https://docs.github.com/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints 核对指纹；如果匹配，请回复 yes。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
编辑器登录窗口（“编辑器登录窗口正在等待响应。”）	你的编辑器打开了一个登录窗口，正在等待你的响应。	编辑器	1. 响应此窗口（或运行 gh auth login，以免依赖该窗口）。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
无网络（“现在无法连接到 …”）或远程仓库为空（“远程仓库还没有任何提交…”）	当前没有互联网连接或网络遭到阻止——这不是密码问题。 / GitHub 副本仍为空；工作线始于首次保存的版本。	终端	网络问题：1. 连接恢复后，再次请求创建工作线。仓库为空且此计算机已有已保存版本：1. GIT_TERMINAL_PROMPT=0 git push -u origin <branch atual>（会显示推送过程）。仓库为空且没有任何已保存版本：1. git add <arquivos, pelo nome>（不会显示任何内容）。 2. git commit -m "primeira versão"（会列出已保存的内容）。 3. 执行上面相同的推送命令。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。
任何其他发现项	我无法读取 GitHub 上的项目副本，原因无法识别。	终端	1. git remote -v — 检查 origin 的地址是否是你的仓库地址。 2. 再次请求创建工作线。	尚未创建任何工作线。完成后，请再叫我——我会从这里继续。（绝不显示 git 错误行。）
⛔ 不要凭空假设项目是什么样的并创建任务分支。基于假设创建的分支第一次使用时就会失败，而用户也不知道原因。此时停下来，比交付看似合理却错误的内容更好。

第一条规则：能查到的就不要问

调查并做出决定。只有确实存在歧义时才提问——并给出你的建议和理由，让用户只需确认。所有你自行做出的假设都写入 sdd/ambiente.md 的 ## Suposições 部分，用户可以用一行进行更正。

第 1 步 — 了解环境（每个仓库一次）

主检出目录是 git worktree list --porcelain 输出中的第一个路径（worktree … 行）。 如果 <主检出目录>/sdd/ambiente.md 存在，请读取并使用——不要重新调查已有的内容。如果不存在，则无需提问，直接调查——但如果请求中已经提供了任务名称，请先进行第 2 步（第 2 项）中的冲突检查：名称重复时立即终止，不写入任何内容，包括 sdd/ambiente.md。

GIT_TERMINAL_PROMPT=0 git remote show origin
git branch -r
git log --oneline -20
git tag --list
git worktree list

并读取以下文件（如果存在）：README.md、package.json、composer.json、requirements.txt、Makefile、.gitignore、.env.example、.github/workflows/、CLAUDE.md、AGENTS.md。

提取以下信息：

• 主分支 — GIT_TERMINAL_PROMPT=0 git remote show origin 返回的“HEAD branch”。它不是“我当前所在的分支”。
• 准备步骤 — 如果 package.json 已纳入版本控制，且 .gitignore 中有 node_modules，则需要在新目录中运行 npm install（否则新目录无法正常使用）。requirements.txt、composer.json 同理。
• Git 之外的本地文件 — 如果 .gitignore 中有 .env，且 .env.example 已纳入版本控制，则新目录需要从主检出目录复制 .env。
• Git 之外的 Agent 技能 — 对于 .claude/skills/ 或 .agents/skills/ 中每个没有任何已纳入版本控制的文件的目录（逐个目录检查 git ls-files <目录>，结果为空），都需要复制到任务分支；否则其中将不存在 sdd-release。
• 编辑器 — 按 code、cursor、subl 的顺序，选择第一个存在的命令（在 bash/zsh 中运行 command -v <名称>，在 PowerShell 中运行 Get-Command <名称>）。
• 分支策略场景，依据仓库证据判断（参照“实战 Git”材料中的标准）：

场景	判断依据	策略	任务分支的终点
A — 持续交付，无审查者	远程没有 develop/staging；提交历史显示直接提交到主分支	简化的 Trunk-Based	直接合并到主分支
B — 通过 Pull Request 交付	历史中有 “Merge pull request #…”；存在 .github/workflows/；有多位作者	GitHub Flow	推送分支并创建 PR
C — 同时支持多个版本	有版本标签 且 远程有 release/* 或 hotfix/* 分支	GitFlow	向 develop 创建 PR（分支从 develop 创建）

始终选择满足需求的最简单方案。A 和 B 难以区分时，选 A（之后添加 PR 很简单；而去掉已经形成习惯的流程则不然）。C 需要两项证据；单人维护的仓库几乎不会属于 C——如果你判断为 C，请重新检查。

将内容按以下格式写入 <主检出目录>/sdd/ambiente.md（如有必要，请创建 sdd/ 目录），每行一个键，方便用户手动更正：

# Ambiente deste repositório

> Gerado pelas skills sdd-new-session/sdd-release. Está errado? Corrija a linha — as skills leem daqui.

- branch_principal: main
- cenario: A (Trunk-Based) — evidência: <o que você viu, ex.: "20 últimos commits diretos na main, sem develop no remoto">
- pasta_das_frentes: ../<nome-do-repo>-frentes
- editor: code
- preparacao: npm install
- arquivos_locais: .env
- deploy: <preencha só se descobriu; senão "a descobrir pelo sdd-release">
- testes: <comando, se descobriu>
- sintaxe: <comando, se descobriu>
- versionamento: nenhum

## Suposições

- assumi <X> porque <Y>

不要提交此文件：它属于用户，由用户决定是否纳入版本控制。

第 2 步 — 创建工作分支

接收用自然语言描述的任务名称，并按顺序执行：

1. 生成 slug：全部小写、用连字符分隔、不带重音符号（例如："Relatório mensal" → relatorio-mensal）。
2. 如果分支或目录已存在，则中止（git show-ref --verify refs/heads/<slug>、 GIT_TERMINAL_PROMPT=0 git ls-remote --heads origin <slug>，以及目录 <pasta_das_frentes>/<slug>）。不要另起一个 名称：请用户提供其他名称。此检查完成前，不得创建任何内容。
3. 执行 GIT_TERMINAL_PROMPT=0 git fetch origin "+refs/heads/<branch-base>:refs/remotes/origin/<branch-base>" （显式 refspec：在只克隆了一个分支的仓库中，仅使用分支名称执行 fetch 不会更新 origin/<branch-base>），然后执行 git worktree add <pasta_das_frentes>/<slug> -b <slug> origin/<branch-base> — 基于 远程状态，而非可能落后的本地状态。<branch-base> 在场景 A、B 中为主分支，在场景 C 中为 develop。 如果场景 C 中没有 origin/develop（GIT_TERMINAL_PROMPT=0 git ls-remote --heads origin develop 结果为空），则在创建 任何内容前停止并说明：标准指向 GitFlow，但没有可供该工作分支创建的 develop。
4. 在新目录中：如有准备步骤，则运行。
5. 将 git 不会带过去的内容复制到工作分支：本地文件（.env）和每个未纳入版本控制的 skill 目录，始终从主检出目录复制（使用绝对路径，并加引号）： mkdir -p "<frente>/.claude/skills" && cp -R "<checkout principal>/.claude/skills/<skill>" "<frente>/.claude/skills/"， .agents/skills/ 也同样处理。 检查当主检出目录中存在 <frente>/.claude/skills/sdd-release（或 .agents/skills/sdd-release）时，新目录中也存在该路径——否则无法完成工作分支。Claude Code 会要求批准写入 .claude/：如果复制被拒绝，不要停止——完成工作分支，并在回复中提供可直接使用的复制命令，以及为所有项目一次性安装 skills 的替代方法 （npx skills add robertodiasduarte/sdd-starter -a <motor> -g -y）。
6. 在编辑器中打开（code <pasta>）。没有编辑器时不要中止：工作分支已准备就绪；显示手动打开的路径。

目录位于仓库之外（../<repo>-frentes/<slug>）：如果放在仓库内，worktree 会显示为未跟踪文件，并弄脏其他所有工作分支的 git status。

**此 skill 不会做什么：**不会提交、推送、删除或集成。所有会销毁或发布内容的操作都只提供为命令 — 或留给 sdd-release skill 处理。

第 3 步 — 回复

遵循如何与学员沟通的格式：Status 应反映实际结果（已完成项标 ✅；若 sdd/ambiente.md 已存在，则第 2 步标 ➖；没有编辑器时，第 4 步标 ➖，并提供手动打开的路径），并将以下各项分别放入“O que foi feito”（1、2 和 4）、“Próximo passo”（3 和 5）以及最后一行。顺序如下：

1. 场景（A、B 或 C）及其依据——说明你实际看到的内容，不要说“看起来像是”。
2. 路径和分支名称。
3. 如何结束此工作分支，提供可直接复制的内容：最后，在新目录中使用 sdd-release skill；或者手动执行该场景的集成命令，然后执行 git worktree remove <pasta> 和 git branch -d <slug>。
4. 所做的假设（如有）以及可以在哪里修正（sdd/ambiente.md）。
5. 在场景 A 中，独自与 AI 协作时：提醒用户在集成前请 AI 审查代码——没有第二个人检查。
6. 最后一行，突出显示： ⚠️ 请在新窗口中继续。当前 Agent 会话仍绑定到打开时所在的目录——任何 cd 都无法改变这一点。Build、commit 和 push 都要在新目录中运行。

每条规则为何存在（阅读前请勿删除）

• 分支从已更新的 origin/<branch-base>（主分支；场景 C 中为 develop）创建——从当前分支创建会继承另一项任务尚未完成的工作， 导致新任务「一开始就带着奇怪的代码」。
• 同一分支不能在两个工作树中打开——Git 会拒绝。因此，不要在任务文件夹中切回主分支：应按对应场景的路径进行集成，并在主检出目录中更新。
• 如果另一项任务先于当前任务集成，当前任务创建时所依据的提交点就已不存在。集成前：GIT_TERMINAL_PROMPT=0 git fetch origin + git merge origin/<branch-base> + 重新运行测试——两个任务之间的冲突会在这时显现。（sdd-release 会执行此操作。）
• 孤立的工作树和分支会越积越多——集成后，执行 git worktree remove 以及 git branch -d。小写的 -d 是一道保护：只会删除已集成的内容。
• 不属于仓库的文件夹有四种截然不同的情况——「在正确的文件夹中打开」和「把项目放进 git」是相反的做法；把两者合成一句话，会让一位学员不知道自己属于哪种情况。单独执行「git init」，则会把整个文件夹连同客户电子表格一起放进首次提交。
• 同步文件夹的问题要优先处理——iCloud、OneDrive、Dropbox 和 Google Drive 会逐个文件同步；.git 和工作树可能损坏或重复。在桌面和文稿文件夹存储于 iCloud 的 Mac 上，路径看不出问题：证据是 iCloud Drive 中的快捷方式。
• 预检要先于任何创建操作——如果没有远程仓库、远程仓库为空或未登录，git worktree add … origin/<principal> 会在中途失败，并留下半成品文件夹；学员不知道该删掉什么。提前停止，说明原因并告知没有创建任何内容，才能让他们直接重新发起请求。
• 缺少 Git 不等于「你正在聊天应用中」——错误的诊断会让人安装已经装好的 Agent。
• Agent 会话不会迁移——打开新文件夹会打开另一个窗口，但运行了技能的会话仍锚定在源目录。没有最后的提醒，整个任务都会在错误的位置完成，而直到提交时才会发现。

---

摘自 RDD 的 SDD Starter — https://github.com/robertodiasduarte/sdd-starter