PR + Commit Workflow

核心用法

pr-commit-workflow 是一套针对现代 AI 辅助开发场景的 Git 工作流规范工具，分为两个独立入口：

• Commit 工作流：通过 references/workflow-commit.md 执行提交检查，使用 references/commit-format.md 的标准化消息格式
• PR 工作流：通过 references/workflow-pr.md 创建或更新 PR，强制使用 references/pr-human-template.md 的人工编写模板，并调用 scripts/build_pr_body.sh 收集环境元数据（AI 模型信息、终端类型等）

关键约束：PR 必须包含用户提供的人工编写意图，禁止 AI 生成或改写。

显著优点

1. 证据链完整性：通过 build_pr_body.sh 自动捕获编码环境（CODEX_MODEL、CLAUDE_MODEL 等），提升 PR 可审计性
2. 人类可读性优先：强制使用人工编写的 PR 模板结构，避免 AI 生成内容的同质化
3. 零依赖设计：纯本地脚本，无外部 API 调用，启动即用的安全边界
4. AGPL-3.0 开源：代码完全可审计，支持 Fork 定制

潜在缺点与局限

• T3 来源风险：个人开发者（joshp123）单点维护，缺乏基金会背书或企业级 SLA
• 环境变量读取：需读取多个 AI 模型的环境变量，虽符合声明功能，但用户需知情共享内容
• 模板刚性：pr-human-template.md 必须"verbatim"使用，灵活性受限
• 无网络功能：无法自动同步 GitHub 评论状态或 CI 检查结果

适合人群

• 使用 Cursor/Codex/Claude 等 AI 工具进行严肃开发的个人开发者
• 希望建立可审计 AI 辅助编码记录的技术团队
• 对 Git 历史整洁度和 PR 可读性有要求的项目

常规风险

• 维护连续性：个人项目存在维护中断风险，建议生产环境 Fork 后自行维护
• 信息泄露：build_pr_body.sh 收集的环境元数据可能包含敏感信息，共享 PR 前需人工审查
• 模板误用：严格遵守 "verbatim" 要求，擅自修改模板可能导致工作流失效
• 版本漂移：引用文件（references/*.md）路径依赖需随 skill 更新同步调整

核心用法

pr-commit-workflow 是一个纯文档型 Workflow Skill，用于在 Agentic 工作流中强制执行高信噪比的代码提交和 Pull Request 规范。它不直接执行代码操作，而是作为决策路由器和规则制定者，指导 Agent 何时、如何、以何种格式创建 commit 或 PR。

双入口设计：

• Commit 入口：调用 references/workflow-commit.md → 使用 references/commit-format.md 的消息格式
• PR 入口：调用 references/workflow-pr.md → 使用 references/pr-human-template.md 的人类可读模板（必须原样使用）

关键强制规则：

• 必须由用户提供人工撰写的 PR 意图说明，禁止 Agent 生成或改写该文本
• PR body 草稿暂存 /tmp，通过 gh pr edit --body-file 更新
• 环境元数据（harness、model、think level 等）由 scripts/build_pr_body.sh 收集，用于审计追踪

显著优点

1. 人机意图隔离：将 "人类为什么做这个改动" 与 "机器怎么实现" 彻底分离，PR 描述回归可读的叙事性文本
2. 可审计的证据链：Commit 附带 checklist 证据，PR 附带环境元数据，形成完整的变更溯源
3. 零外部依赖：纯 Markdown + Shell 脚本，无第三方包，无网络调用
4. AGPL-3.0 开源：协议透明，社区可审查、可分叉

潜在缺点与局限

• 人工摩擦：强制要求人类撰写意图，在快速迭代场景中可能拖慢节奏
• GitHub CLI 依赖：gh pr edit 命令要求环境预装并认证 gh CLI
• 模板刚性：pr-human-template.md 必须原样使用，定制化需修改源码
• T3 来源风险：个人开发者维护，长期维护承诺存疑

适合人群

• 需要合规审计的企业工程团队（金融、医疗、关键基础设施）
• 追求可解释 AI 的 Agentic 工作流设计者
• 开源项目维护者，希望 PR 历史具备叙事性和可追溯性
• 对 "AI 生成 PR 描述泛滥" 感到疲劳的开发者

常规风险

| 风险类型 | 级别 | 说明 |

|---------|------|------|

| 来源可信度 | 中 | T3 个人开发者，建议通过其他渠道验证作者信誉 |

| 供应链攻击 | 极低 | 无第三方依赖，单 Shell 脚本功能透明 |

| 隐私泄露 | 低 | 仅收集环境元数据（model、终端类型等），无敏感信息 |

| 误用风险 | 中 | 若用户绕过 "人工意图" 要求自行粘贴 AI 生成文本，则失去核心设计价值 |