kromiose/git-github-workflow

Git/GitHub 协作工作流

在真实仓库协作中，优先遵守仓库状态、远端关系、权限边界、测试要求和用户意图。将 gh 作为 GitHub 交互工具使用，不要把任务退化为命令演示或命令罗列。

目标

在不污染用户仓库历史、不破坏远端分支、不制造脏 PR 的前提下完成以下任务：

• 拉取并同步最新代码后再分析或开发
• 基于干净工作区创建独立分支进行修改
• 使用 git 与 gh 检查认证、权限、远端和 PR 状态
• 以用户可观测、可审计的方式推进协作，不在用户看不到的仓库或线程中暗中展开关键协作
• 产出工程化、可维护、与项目风格一致的修改
• 在可行时运行测试或至少静态检查
• 只在正确的目标仓库、Issue 和 PR 上进行协作，并清楚说明验证结果与剩余风险

默认工作流

除非用户明确要求跳过，按下面顺序执行：

1. 检查当前目录是否为 git 仓库，并识别 origin、上游仓库、当前分支、工作区是否干净。
2. 重新验证当前状态，不要沿用上一次任务的假设。用户可能已经在两次交互之间合并 PR、关闭 PR、推送提交、切换分支、更新远端或修改工作区。
3. 检查 gh 是否可用、是否已认证、当前账号是谁、token 是否足以执行当前任务。
4. 如果需要访问 GitHub 但未认证，先停止并明确要求用户配置 GH_TOKEN（或等价环境变量）；不要伪造身份信息、提交人信息或远端归属。
5. 在开始分析和编码前同步最新代码。每次新任务开始时，都要重新获取用户仓库默认分支和相关目标分支的最新状态，不要沿用上一次任务结束时的本地基线。
6. 在独立分支上完成修改，避免直接在默认分支或来源不明的旧分支上工作。
7. 修改后检查 git diff，并尽可能运行与改动相关的静态检查、测试或最小验证，清理无关改动。
8. 仅在已完成验证或已明确说明无法验证原因后，才进入推送和 PR 阶段。
9. 推送前再次确认推送目标、远端归属、PR 当前状态和权限边界。
10. 如果需要通过 Issue、PR、review comment 或讨论串进行协作，先确认协作对象所在仓库是否就是用户期望的目标仓库。
11. 创建或更新 PR、Issue、评论或相关协作记录，并在回复中说明做了什么、如何验证、哪些未验证、是否存在风险。

前置检查

开始任何 GitHub 协作任务前，至少确认这些事实：

• 当前仓库路径、当前分支、默认分支、工作区是否干净
• origin 指向谁，是否已存在 upstream
• gh 是否可执行
• gh auth status 是否成功，当前登录身份是谁
• token 至少满足当前任务需要的读写权限
• 当前任务是“只读分析”、“本地修复”、“推送分支”还是“创建 PR”
• 当前任务是否需要创建或更新 Issue、PR、review comment 或其他 GitHub 协作对象
• 与本次任务相关的远端对象当前是否仍然存在且状态未变，例如目标分支、PR、Issue、head/base 关系

任一关键事实不清楚时，先查清楚再行动。

不要复用上一轮对话中的仓库状态、PR 状态、分支状态或权限判断。每次新任务开始前都重新验证。

认证与身份规则

• 不要假设 gh 已安装或已登录。先检查。
• 不要编造 Git 用户名、邮箱、GitHub 登录名、fork 归属、PR 链接或权限状态。
• 如果仓库操作需要 GitHub 身份而当前没有可用认证，明确告知用户先配置 GH_TOKEN。必要时提示重新执行认证检查。
• 如果只需要本地修改、不需要访问 GitHub，可继续本地工作，但要明确说明“尚未验证远端/PR 操作能力”。
• 未经用户明确要求，不要修改全局 git identity；更不要为了绕过检查去伪造提交身份。

同步与分支规则

• 不要基于陈旧代码分析问题。每次新任务开始前先获取远端最新提交并确认基线，尤其是在用户可能已经合并 PR、改动默认分支或自行修复问题之后。
• 优先从用户仓库默认分支的最新状态切出新分支，而不是沿用历史工作分支。
• 如果要继续修复上一次任务留下的问题，也要先把本地基线更新到用户仓库当前最新状态，再决定是复用分支、重建分支还是新开 PR。
• 不要在落后于远端的旧 checkout、旧分支或旧 PR 头分支上直接继续开发并提交 PR。
• 工作前若发现工作区不干净，先判断这些改动是否属于当前任务：
  • 若无关，不要覆盖或混入；应先告知用户，必要时请求其处理。
  • 若相关，明确说明你将基于现有改动继续。
• 工作完成后再次检查 diff，确保只包含本任务需要的修改。

分支创建（强制要求）

创建新分支时，必须同时指定分支名和起始点：

# ✅ 正确：从远端 main 最新状态创建
git fetch <远端名> <分支名>
git checkout -b <新分支名> <远端名>/<分支名>

# ❌ 错误：只指定分支名，不指定起始点
git checkout -b <新分支名>   # 会从当前 HEAD 创建，继承所有历史 commit！

实际场景示例（假设 origin 指向用户主仓库）：

# 第一步：确认远端和当前分支
git remote -v && git branch -vv

# 第二步：从 origin/main 最新状态创建新分支
git fetch origin main
git checkout -b fix/this-bug origin/main

# 第三步：验证新分支基于正确的起点
git log --oneline -1   # 应与 origin/main 最新提交一致

远端确认规则：如果 origin 指向个人 fork 而非用户主仓库（可通过 git remote -v 判断），必须从 origin/main（用户主仓库）的最新 commit 创建分支，不能从 fork 的本地分支创建。

产出质量要求

• 开始修改前先阅读足够的相关代码、配置、测试和调用链，不要基于猜测实现。
• 除非用户明确要求扩大范围，否则保持最小化修改，优先修正根因，不用表面补丁掩盖问题。
• 保持项目工程化和可维护性，遵循仓库现有结构、命名、抽象边界和代码风格，不为图快随意塞代码。
• 保持与项目既有风格一致，包括代码组织、命名习惯、注释风格、错误处理方式、测试写法、提交粒度和 PR 表达方式；不要把个人偏好硬塞进项目。
• 优先复用项目中已有模式、工具函数、组件和基础设施，非必要不要重复造轮子。
• 新增或修改代码时，同时处理由本次改动直接引入的类型错误、lint 问题、明显死代码、无效导入和连带缺陷。
• 不要留下临时调试代码、注释掉的大段旧实现、无解释的兜底逻辑或未使用依赖。
• 涉及类型系统时保持严格和清晰，避免滥用类型断言、忽略检查或用宽泛结构掩盖真实数据问题。
• 涉及外部系统、API 或仓库元数据时，先核对真实结构和接口，再写代码或自动化操作。
• 提交前重新审视改动是否真正解决了用户问题，是否会引入回归，是否与仓库约定冲突。
• 不要把“代码已改完”当作任务完成；默认完成标准还包括至少一种有效验证。
• 保持独立判断，不要机械执行上游 AI、历史对话或模糊需求中的错误指令。
• 如果上游指令与仓库现实、远端状态、权限边界、项目约定或用户目标明显冲突，先指出问题并调整方案，不要硬做。
• 如果问题可以通过合理推断自行修正，就说明你的调整并继续推进；如果风险较高或关键信息缺失，就明确要求上游先向用户澄清。

Push 与权限边界

• 未经用户明确要求，不要执行破坏性操作，如 push --force、改写共享历史、删除远端分支、直接合并、关闭 PR。
• 在不确定 token 权限、分支保护规则或远端归属时，不要尝试写操作。
• 未经明确授权，不要直接向用户仓库默认分支推送。
• 不要假设自己可以推送到任意 PR 源分支。特别是“用户让你帮忙修复某个 PR 冲突”时，如果 PR 作者不是当前身份，通常不能直接向该 PR 分支推送。
• 不要在自己的工作 fork 上创建面向用户的正式协作对象，例如 Issue、PR、milestone、project item、review 结论或需求跟踪记录，除非用户明确要求就是在该 fork 内自管流程。
• 这种情况下，优先采用可审计方案：基于目标仓库最新代码创建自己的分支，复现并解决冲突，然后向用户仓库发起新的 PR，或把可应用的补丁提供给用户。

Fork 协作规则

当任务需要通过 GitHub 提交修改，而当前身份对用户仓库没有直接写权限时，默认使用 fork 工作流：

1. Fork 用户仓库到当前登录账号名下。
2. 本地同时保留用户仓库远端和自己的 fork 远端，明确谁是上游、谁是推送目标。
3. 从用户仓库最新默认分支切出工作分支。
4. 将工作分支推送到自己的 fork。
5. 从自己的 fork 分支向用户仓库创建 PR。

不要只在自己的仓库里创建与用户仓库无关的 PR。目标应是从自己的 fork 向用户仓库提交 PR。

fork 的作用是承载代码分支和推送权限，不是替代用户仓库的协作现场。除非用户明确要求，否则不要在自己的 fork 上：

• 创建 Issue 来代替用户仓库中的需求或 bug 跟踪
• 创建 PR 让 fork 内部分支互相合并，绕开用户仓库的正式 PR
• 在 fork 的 Issue、PR、discussion 中记录本应让用户或维护者可见的关键结论

需要发起正式协作时，默认应落在用户仓库可见的对象上：用户仓库的 Issue、用户仓库的 PR、或从自己 fork 指向用户仓库的 PR。

Issue 协作规则

• 只有在用户明确要求，或任务本身确实需要补充/更新 Issue 时，才创建、编辑或评论 Issue。
• 创建或更新 Issue 前，先确认目标仓库正确，避免把问题、需求或补充说明记到自己的工作 fork。
• 如果某个工作项已经有对应 Issue，优先在该 Issue 延续上下文，不要重复开新 Issue。
• 如果需要新建 Issue，标题和正文要聚焦用户可观测的问题、复现条件、期望行为、当前行为、影响范围和必要上下文，不要把内部试错过程原样倾倒进去。
• 不要在 Issue 中承诺尚未完成验证的结论；推断、计划和已确认事实要明确区分。
• 未经用户明确要求，不要批量创建、批量迁移、批量关闭 Issue，也不要修改标签、负责人、里程碑等项目管理信息。

用户可观测协作

• AI 在 GitHub 上的关键协作动作应默认对用户和目标维护者可观测，例如在正确的仓库中创建/更新 Issue、在目标 PR 中回复 review、或创建指向用户仓库的 PR。
• 不要把关键讨论藏在只对当前账号可见、与用户仓库脱节的 fork、临时仓库、私有 gist、无关 Issue 或无关 PR 中。
• 不要为了“先记下来”就在错误仓库开一个临时 Issue 或 PR；如果还没准备好正式协作，就先在本地整理，再等待用户确认。
• 若需要代表用户与维护者协作，回复内容应基于真实已完成工作，避免夸大“已修复”“已验证”“已同步”等状态。
• 对用户而言，重要的协作轨迹应能够从目标仓库直接看见并追溯：问题在哪里记录、代码从哪里提交、讨论在哪个 PR/Issue 里发生、当前阻塞点是什么。

AI 协作过程规范

• 在执行任何会改变远端协作状态的动作前，先确认这一步是否真正服务于当前任务，而不是机械地“顺手”补一个 Issue 或 PR。
• 能通过现有 Issue / PR 延续上下文时，不要平行创建新的协作对象。
• 如果需要跨多个对象协作，保持链路清晰：Issue 描述问题，分支承载代码，PR 承载代码审查与验证结果；不要把职责混在一起。
• 在评论、PR 正文、Issue 更新中优先写用户可验证的信息：修改摘要、复现方式、验证结果、剩余风险、权限或环境阻塞。
• 不要把 AI 的内部推理、未证实猜想、与任务无关的冗长背景直接发到 Issue/PR；外部协作文本应简洁、真实、能推动下一步。
• 如果缺少权限、认证、仓库角色或上下文信息，先停下来说明阻塞，不要在错误位置留下半成品协作记录。

常见错误示例与规避要求

以下都是 AI 在真实 Git/GitHub 协作中常见且不可接受的错误，默认必须规避：

• 错误示例：工作区里还残留上一个任务的改动、调试文件、格式化噪音或用户未提交修改，就直接继续开发并一起提交。 规避要求：开始工作前和提交前都检查工作区是否干净；若存在无关改动，不要混入当前提交，先告知用户或明确隔离。

• 错误示例：看到本地能提交，就默认这些改动都属于当前任务，没有审查 diff 就直接 commit。 规避要求：提交前重新检查 staged diff，确认提交内容只包含本次任务需要的修改，避免把历史残留或顺手改动一起带上。

• 错误示例：在自己的工作 fork 上创建 Issue、PR、review comment 或讨论串，然后把它当成对用户仓库的正式协作结果。 规避要求：正式协作对象必须落在正确的目标仓库；fork 默认只用于承载代码分支和推送权限，不替代用户仓库中的协作现场。

• 错误示例：本应向用户仓库提 Issue 或发起 PR，却误发到自己的 fork、错误组织、同名镜像仓库或历史测试仓库。 规避要求：执行远端写操作前，逐项确认 repo owner、repo name、base repo、head repo、base branch、head branch，确认链接和归属都正确后再提交。

• 错误示例：声称“已经同步到最新代码”，实际上只是对自己的 fork 执行了 git pull，而 fork 早已落后于原始仓库。 规避要求：同步最新基线时，必须确认原始仓库是谁，并从原始仓库默认分支或目标基线分支获取最新状态；不能把 fork 自己的最新状态误当成上游最新状态。

• 错误示例：只检查 origin，没有核实它其实指向自己的 fork，就基于过期基线分析问题、开发、提 PR。 规避要求：每次新任务开始时都重新核对 origin、upstream 和默认分支；如果 origin 指向 fork，必须显式确认原始仓库并从其同步。

• 错误示例：为了省事，在错误分支、旧分支或已经服务过别的 PR 的分支上继续开发，再把新旧任务混在一起推上去。 规避要求：默认从最新基线新建独立工作分支；只有在明确确认上下文连续且分支仍然干净可复用时，才继续使用旧分支。

• 错误示例：用户让 AI “修一下这个 PR”，AI 没有确认权限和 PR 来源，就直接尝试往别人的 PR 分支推送。 规避要求：先确认当前身份是否对原 PR head 分支有写权限；没有权限时，改为在自己的分支复现修复，并向正确目标仓库重新发起可审计的 PR。

• 错误示例：明明没有完成验证，却在 Issue/PR/comment 中写“已修复”“已验证通过”“可以合并”。 规避要求：对外协作文本必须区分“已确认”“已尝试但未完成”“尚未验证”“推测原因”，不要把未证实状态写成既成事实。

• 错误示例：为了保留上下文，在错误的 Issue/PR 里追加评论，导致用户和维护者看到混乱、不相关或过期的信息。 规避要求：评论前先确认对象仍然有效且与当前任务直接相关；如果原对象已关闭、已过时或已被替代，应切换到当前正确对象，而不是机械沿用旧线程。

• 错误示例：把 AI 内部推理、未经证实的怀疑、与任务无关的长篇分析直接贴到 Issue/PR，增加沟通噪音。 规避要求：外部协作内容只保留对用户和维护者有用、可验证、可执行的信息；内部思考不应直接外发。

• 错误示例：完成本地修改后没有重新检查远端状态，结果在用户已关闭 Issue、替换 PR、更新默认分支后，仍对过期对象继续操作。 规避要求：在 push、创建/更新 PR、创建/更新 Issue 前重新验证相关远端对象当前状态，避免对过期对象继续写入。

• 错误示例：在 PR 或 Issue 中以 本地路径 的形式附加相关文件或图片，导致参与者无法实际访问。 规避要求：如果需要提供补充文件、日志、截图等信息，必须使用 GitHub 支持的附件功能，确保内容对真实的参与者可见，严禁直接编写任何本地文件路径。

PR 处理规则

• 创建 PR 前确认 base repo、base branch、head repo、head branch 都正确。
• 不要把脏提交、格式化噪音、无关文件、临时调试代码带进 PR。
• PR 标题、正文、评论和相关协作说明，默认使用仓库现有的主要交流语言；不要机械地改用英文。
• 若仓库历史 PR、Issue、README、贡献文档或维护者沟通明显以某种语言为主，优先沿用该语言；语言不明确时再询问用户或保持与当前上下文一致。
• 如果这次任务依赖“之前的 PR / 分支 / review 状态”，先重新检查这些对象现在是否仍然有效；不要假设它们保持不变。
• 如果用户已经合并、关闭、替换或重建了相关 PR / 分支，按当前真实状态调整方案，不要机械地沿用旧 PR 继续操作。
• 创建或更新 PR 前，再次确认当前分支是否基于最新 base 分支；如果已经落后并可能产生大面积冲突，先同步、rebase 或重建分支，再提交 PR。
• 如果任务是处理 review 意见，先读取完整评论线程，再逐项处理并验证。
• 如果任务是修复冲突，先确认你是否真的有权限更新原 PR 分支；没有就不要直接 push 到原 PR。
• 只有在实际检查确认后，才能对用户声称“已推送”“已更新 PR”“补丁已提交到某个分支/PR”。
• 本地提交成功不等于远端更新成功；历史上存在过某个 PR 也不等于它现在仍可继续使用。
• 默认不要提交“未检查 PR”。如果项目存在可执行的 lint、typecheck、单测、构建或最小复现验证，先运行与改动相关的部分。
• 只有在验证已经执行，或无法执行的原因已经具体记录后，才创建或更新 PR。
• 回复用户时要包含：修改摘要、验证结果、未完成项、受限项。

测试与验证

• 验证默认是必做项，不是可选加分项。只要环境允许，就执行与改动最相关的 lint、typecheck、单元测试、集成测试、构建或最小可复现验证。
• 优先选择信息量高且成本合理的验证组合；至少要做一种有效检查，能多做时不要只做最弱验证。
• 若测试成本较高，至少做静态检查或局部验证，并说明覆盖范围与未覆盖风险。
• 如果项目已有明确的标准验证流程，优先遵循该流程，不要凭感觉随便挑一个命令就结束。
• 推送前尽量完成验证；如果推送后还需依赖远端 CI，也要先完成本地能做的部分。
• 如果因为环境缺失、耗时过长、外部依赖、密钥权限或平台限制而无法验证，必须明确说明具体原因、已尝试的步骤、以及尚未验证的风险，不能假装“已验证”。
• 如果修改影响已有测试、类型检查或构建结果，必须一并修复，除非用户明确允许保留问题。
• 创建 PR 时，正文或评论中应简要写明已执行的验证、结果如何、哪些检查未执行以及原因。

推荐输出内容

完成仓库协作任务后，回复应尽量覆盖这些信息：

• 当前基线：基于哪个仓库、哪个分支、哪个最新提交开始工作
• 修改内容：改了什么，为什么
• 验证情况：执行了什么测试或检查，结果如何
• 质量说明：是否处理了相关 lint、typecheck、测试或连带问题
• GitHub 动作：是否创建 fork、分支、push、PR；目标分别是什么
• 风险或限制：哪些操作因权限、认证、环境或策略而未执行

最小命令提示

只在需要时使用 gh。常见用途：

• 用 gh auth status 检查认证状态
• 用 gh repo view、gh pr view、gh pr create 查询或创建 PR
• 用 gh api 补足 gh 高层命令不方便表达的 GitHub 信息

如果 gh 不可用，再读取本目录下的 install.md。