production-parity-skill-builder

生产环境一致性技能构建器

为单个应用构建一项技能。生成的技能应确保本地和非生产环境在行为上与生产环境保持一致，同时明确说明并测试所有有意的差异。

创意归功于：GitHub 用户 @dm。

生产环境是参考契约。本地、CI、PR、预览和预发布环境可以采用较轻量的基础设施，但必须模拟生产环境的行为，或记录差异并配备相应的补偿性测试。例如，生产环境中有 authentik 组限制，而本地环境没有，这属于一致性缺陷，不是无伤大雅的便利措施。

工作流

1. 先检查，再提问

先从代码仓库中收集证据。不要要求用户解释那些可以从文件中查明的内容。

视情况检查：

• 文档：README*、docs/、ADR、操作手册、入门指南、本地设置、部署说明
• 应用代码：配置加载、身份验证/授权、多租户、功能标记、服务客户端、计划任务、Webhook
• 测试：单元测试、集成测试、端到端测试、冒烟测试、契约测试、身份验证 fixture、种子数据、工厂
• 本地设置：Dockerfile、compose 文件、开发容器、脚本、种子工具、Makefile、软件包脚本
• CI 和预览：GitHub Actions、GitLab CI、Buildkite、预览部署配置、测试矩阵
• 基础设施：Terraform、Pulumi、CDK、Helm、Kustomize、Kubernetes 清单、Cloudflare/Vercel/Netlify/Fly/Render 配置
• 生产环境描述文件：环境变量 schema、密钥名称、IdP/OIDC/SAML 设置、入口、网络策略、运行时版本、数据库扩展、队列、对象存储、cron、外部提供商配置

使用 rg --files 和针对性的 rg 搜索。搜索环境名称和对一致性敏感的术语：

prod|production|staging|preview|pr|local|dev|ci|docker|compose|k8s|helm|terraform|pulumi|auth|oidc|saml|jwt|group|role|claim|permission|feature flag|secret|env|webhook|cron|queue|seed|fixture|migration

2. 构建一致性映射

编写生成的技能之前，先创建一份工作用的一致性映射。针对每个方面，记录：

• 生产环境的真实依据：文件、清单、文档、仪表板导出或用户回答
• 非生产环境的对应实现：本地、CI、PR/预览、预发布
• 偏差风险：如果两者不同，会改变哪些用户可见行为或安全行为
• 当前防护措施：测试、schema 检查、冒烟测试、契约测试、策略检查，或无
• 修复模式：模拟、填充种子数据、契约测试、验证配置、解析基础设施，或记录明确的差异
• 当代码仓库无法给出答案时的负责人或升级途径

选择方面和检查项时，加载 resources/parity-surface-catalog.md。将目录用作检查清单，而不是认为每个应用都需要其中的所有方面。

3. 提出有针对性的问题

如果当前 Agent harness 提供提问功能，请使用它：AskUserQuestion、request_user_input、ask_question，或等效功能。如果没有结构化提问工具，就用简洁的纯文本提问。

仅在检查之后提问。只问那些会影响生成的技能或必要修复的问题。

提问规则：

• 除非两个选项紧密相关，否则每次只问一个决策问题。
• 如果答案范围有限，优先提供结构化选项。
• 说明引发问题的证据。
• 优先推荐最安全的选项，同时指出其中的权衡。
• 将每个答案记录到生成的技能中；不要只把决策留在聊天里。

加载 resources/question-patterns.md，以使用可复用的问题模板。

比较模拟器、本地服务、托管沙盒或测试工具选项之前，先构建一致性映射。如果代码仓库中的证据无法确定其中影响重大的选择，应将已知的一致性契约和约束交由 evaluate-existing-solutions 处理；不要让工具搜索决定生产环境保真度的标准。

示例：

Production appears to require authentik group `app-users` for login, but local and PR setup seed no equivalent restriction.
How should non-production enforce this?

1. Mirror production with seeded IdP group membership. Recommended: catches auth drift while keeping local deterministic.
2. Use a lightweight OIDC/authentik emulator with the same required claim. Good when running real authentik locally is too heavy.
3. Keep local unrestricted, but add contract/E2E tests that fail unless prod-only group enforcement is represented. Faster local login, higher residual drift risk.

4. 生成应用专属技能

为特定应用编写一项新技能，通常命名为 <app-name>-production-parity，除非用户或代码库的命名约定另有要求。

将生成的技能直接存放在目标应用的代码库中。切勿将生成的应用专属技能放在 ~/.agents/skills、~/.codex/skills、~/.claude/skills 或 $CODEX_HOME/skills 等用户／全局目录中。

检查应用代码库，选择项目本地的位置：

• 如果应用已有项目本地技能目录，请沿用该约定。
• 如果代码库使用 Claude 项目配置，优先使用 .claude/skills/<app-name>-production-parity/SKILL.md。
• 如果代码库使用 Codex 项目配置，优先使用 .codex/skills/<app-name>-production-parity/SKILL.md。
• 如果没有项目本地技能约定，请在创建新约定之前，用一个简洁的 harness 问题询问用户。
• 如果唯一可用的技能目录是全局／用户目录，请勿使用；询问用户技能应存放在项目代码库的什么位置。

生成的技能必须包含：

• frontmatter，其中的描述应在涉及该应用的奇偶性、漂移、本地／生产环境不匹配、身份验证／配置／基础设施差异以及环境设置时触发
• 一个“App Parity Contract”（应用奇偶性契约）章节，明确生产环境是参考标准，并列出有意设置的非生产环境差异
• 一个“Production Truth Sources”（生产环境事实来源）章节，列出精确的文件路径、清单、文档、命令或经用户确认的来源
• 一个“Inspection Workflow”（检查工作流）章节，列出与代码库相关的命令和需要读取的文件
• 一个针对该应用量身定制的“Parity Surfaces”（奇偶性检查面）章节，而非泛泛的检查清单
• 一个“Drift Checks”（漂移检查）章节，列出 Agent 应运行的具体测试、脚本、架构定义或手动检查
• 一个“Fix Patterns”（修复模式）章节，说明如何在该应用的架构中消除漂移
• 一个“Question Protocol”（提问流程）章节，指示 Agent 对于无法从来源中得出答案的问题，应使用当前 harness 的提问功能
• 一个“Output Contract”（输出约定）章节，规定每次后续运行都要报告：已检查的文件、发现的风险、所做的修复、运行的测试以及明确列出的剩余差异

从 resources/generated-skill-template.md 开始，但要删除不相关的章节，并使用针对该应用的证据替换占位内容。

5. 明确保障措施；仅在获得授权后添加

生成的技能应列出目标应用所需的、范围明确的检查：

• 配置奇偶性：针对必需环境变量和仅限生产环境的限制进行架构验证
• 身份验证奇偶性：针对必需的 IdP 群组、角色、声明、重定向 URI、Cookie 和会话策略进行测试
• 夹具奇偶性：检查已播种的用户、租户、功能标志、角色、套餐、配额和数据生命周期状态
• 基础设施奇偶性：解析或对比部署清单与本地／预览环境清单，检查与安全相关的设置
• 提供商奇偶性：针对外部 API、Webhook、电子邮件、存储、队列和支付提供商进行契约测试，或使用录制的夹具
• 运行时奇偶性：固定语言运行时、数据库、扩展、镜像标签和构建命令的版本
• 冒烟测试奇偶性：执行预览／预发布环境冒烟测试，证明合并前应用可以在与生产环境等效的限制下启动

当某项差异是有意设置的，必须说明具体原因，并提供补偿性防护措施。“本地环境更方便”并不足以构成理由。

只有在用户明确要求修复奇偶性问题，或在发现差异后授权额外修改时，才在应用代码、测试、配置、夹具或基础设施中实现这些检查。仅要求创建可复用技能，只授权创建技能产物，不授权对应用或基础设施进行无关修改。否则，应在生成的技能／输出中写明精确的防护契约和建议放置位置，并保持目标应用不变。

6. 验证生成的技能

完成前：

1. 重新阅读生成的技能，假设是在一个全新的对话线程中调用它。
2. 确认每项特定于应用的说法都有仓库来源或记录下来的用户回答作为依据。
3. 确认没有保留不适用于该应用的通用检查项。
4. 确认生成的技能路径位于目标应用仓库内，而不是用户级或全局技能文件夹中。
5. 如果执行环境或仓库中提供技能验证命令，请运行该命令。
6. 如果无法运行验证，请准确说明原因。

输出

返回：

• 生成的技能路径
• 确认生成的技能存储在目标项目仓库内
• 检查过的文件和目录
• 创建过程中发现的最高风险功能一致性差异
• 提出的问题和记录的决定
• 运行的测试或验证
• 如果发现但未修复差异，请提供建议的后续修复方案

不要将通用的一致性报告作为最终成果。主要交付物应是可复用的、特定于该应用的技能。