Back to Details

production-parity-skill-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Production Parity Skill Builder

生产环境一致性Skill构建器

Build a skill for one application. The generated skill's job is to keep local and non-production environments behaviorally aligned with production, while making every intentional difference explicit and tested.
Idea credit: GitHub user @dm.
Production is the reference contract. Local, CI, PR, preview, and staging may use lighter infrastructure, but they must either emulate production behavior or document the divergence with compensating tests. A production authentik group restriction that is absent locally is a parity bug, not a harmless convenience.
为单个应用构建一款Skill。生成的Skill的职责是保持本地及非生产环境的行为与生产环境一致，同时将所有有意为之的差异明确记录并进行测试。
创意来源：GitHub用户@dm。
生产环境是参考标准。本地、CI、PR、预览和预发布环境可使用更轻量化的基础设施，但必须要么模拟生产环境的行为，要么记录偏差并补充相应的测试。生产环境中存在的authentik组限制在本地环境缺失，这属于一致性Bug，而非无害的便利设置。

Workflow

工作流程

1. Inspect Before Asking

1. 先检查再提问

First build evidence from the repository. Do not ask the user to explain what can be discovered from files.
Inspect, as applicable:
  • docs: 
    README*
    , 
    docs/
    , ADRs, runbooks, onboarding, local setup, deployment notes
  • app code: config loading, auth/authz, tenancy, feature flags, service clients, scheduled jobs, webhooks
  • tests: unit, integration, E2E, smoke, contract, auth fixtures, seed data, factories
  • local setup: Dockerfile, compose files, devcontainers, scripts, seeders, Makefiles, package scripts
  • CI and previews: GitHub Actions, GitLab CI, Buildkite, preview deployment config, test matrices
  • infra: Terraform, Pulumi, CDK, Helm, Kustomize, Kubernetes manifests, Cloudflare/Vercel/Netlify/Fly/Render config
  • production descriptors: env schemas, secret names, IdP/OIDC/SAML settings, ingress, network policy, runtime versions, database extensions, queues, object storage, cron, external provider config
Use 
rg --files
and targeted 
rg
searches. Search for environment names and parity-sensitive terms:
text
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
首先从代码仓库中收集证据。不要要求用户解释可从文件中发现的内容。
根据实际情况检查以下内容：
  • 文档：
    README*
    、
    docs/
    、架构决策记录（ADRs）、运行手册、入职指南、本地设置说明、部署笔记
  • 应用代码：配置加载、认证/授权、租户管理、功能标志、服务客户端、定时任务、Webhook
  • 测试：单元测试、集成测试、端到端（E2E）测试、冒烟测试、契约测试、认证测试夹具、种子数据、工厂类
  • 本地设置：Dockerfile、Compose文件、开发容器（devcontainers）、脚本、数据填充器（seeders）、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
搜索。搜索环境名称和对一致性敏感的术语：
text
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. Build The Parity Map

2. 构建一致性映射表

Create a working parity map before writing the generated skill. For each surface, record:
  • production truth source: file, manifest, doc, dashboard export, or user answer
  • non-production representation: local, CI, PR/preview, staging
  • drift risk: what user-visible or security behavior changes if this differs
  • current guard: test, schema check, smoke test, contract test, policy check, or none
  • fix pattern: emulate, seed, contract-test, validate config, parse infra, or document explicit divergence
  • owner or escalation path when the repo cannot answer it
Load 
resources/parity-surface-catalog.md
when choosing surfaces and checks. Use the catalog as a checklist, not as a claim that every app needs every surface.
在编写生成的Skill之前，先创建一份可用的一致性映射表。针对每个维度，记录：
  • 生产环境事实来源：文件、清单、文档、仪表板导出内容或用户回答
  • 非生产环境表现：本地、CI、PR/预览、预发布
  • 偏差风险：如果该维度出现差异，会对用户可见行为或安全行为造成哪些改变
  • 当前防护措施：测试、schema检查、冒烟测试、契约测试、策略检查或无防护
  • 修复模式：模拟、填充数据、契约测试、验证配置、解析基础设施配置或记录明确的偏差
  • 当仓库无法解答时的负责人或升级路径
选择维度和检查项时，可参考
resources/parity-surface-catalog.md
。将该目录用作检查清单，而非要求每个应用都覆盖所有维度。

3. Ask Targeted Questions

3. 提出针对性问题

Use the harness's available ask-question facility when it exists: 
AskUserQuestion
, 
request_user_input
, 
ask_question
, or the equivalent in the active agent harness. If no structured question tool is available, ask a concise plain-text question.
Ask only after inspection. Ask only questions that change the generated skill or required fixes.
Question rules:
  • Ask one decision at a time unless two options are tightly coupled.
  • Prefer structured options when the answer space is enumerable.
  • Include the evidence that triggered the question.
  • Recommend the safest option first, but name the tradeoff.
  • Capture each answer into the generated skill; do not leave decisions only in chat.
Load 
resources/question-patterns.md
for reusable question shapes.
Example:
markdown
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.
使用harness提供的提问工具（如
AskUserQuestion
、
request_user_input
、
ask_question
或当前Agent harness中的等效工具）。如果没有结构化提问工具，则提出简洁的纯文本问题。
仅在完成检查后提问。仅提出会影响生成的Skill或所需修复的问题。
提问规则：
  • 一次只提出一个决策问题，除非两个选项紧密关联。
  • 当答案范围可枚举时，优先使用结构化选项。
  • 附上触发问题的证据。
  • 首先推荐最安全的选项，但说明权衡利弊。
  • 将每个答案记录到生成的Skill中；不要仅将决策留在聊天记录里。
可参考
resources/question-patterns.md
中的可复用提问模板。
示例：
markdown
生产环境似乎要求authentik组`app-users`才能登录，但本地和PR设置中未添加等效限制。
非生产环境应如何执行此限制？

1. 通过填充IdP组成员来镜像生产环境。推荐：在保持本地环境确定性的同时，捕获认证偏差。
2. 使用轻量级OIDC/authentik模拟器，并设置相同的必填声明。适用于本地运行真实authentik过于繁重的场景。
3. 保持本地环境无限制，但添加契约/E2E测试，若未体现生产环境独有的组限制则测试失败。本地登录速度更快，但残留偏差风险更高。

4. Generate The App-Specific Skill

4. 生成特定于应用的Skill

Write a new skill for the specific app, normally named 
<app-name>-production-parity
unless the user or repo naming convention suggests otherwise.
Store the generated skill directly in the target application's repository. Never create the generated app-specific skill in a user/global folder such as 
~/.agents/skills
, 
~/.codex/skills
, 
~/.claude/skills
, or 
$CODEX_HOME/skills
.
Choose the project-local location by inspecting the app repo:
  • If the app already has a project-local skills directory, use that convention.
  • Prefer 
    .claude/skills/<app-name>-production-parity/SKILL.md
    when the repo uses Claude project config.
  • Prefer 
    .codex/skills/<app-name>-production-parity/SKILL.md
    when the repo uses Codex project config.
  • If no project-local skill convention exists, ask one concise harness question before creating a new convention.
  • If the only available skill directories are global/user folders, do not use them; ask where in the project repo the skill should live.
The generated skill must include:
  • frontmatter whose description triggers on parity, drift, local/prod mismatch, auth/config/infra differences, and environment setup for that app
  • an "App Parity Contract" that names production as the reference and lists intentional non-prod divergences
  • "Production Truth Sources" with exact file paths, manifests, docs, commands, or user-confirmed sources
  • "Inspection Workflow" with repo-specific commands and files to read
  • "Parity Surfaces" tailored to the app, not a generic checklist dump
  • "Drift Checks" with concrete tests, scripts, schemas, or manual checks the agent should run
  • "Fix Patterns" that explain how to close drift in this app's architecture
  • "Question Protocol" instructing the agent to use the active harness's ask-question facility for source-unanswerable decisions
  • "Output Contract" for every future run: inspected files, risks found, fixes made, tests run, remaining explicit divergences
Start from 
resources/generated-skill-template.md
, but remove irrelevant sections and replace placeholders with app-specific evidence.
为特定应用编写新的Skill，通常命名为
<app-name>-production-parity
，除非用户或仓库命名惯例有其他建议。
将生成的Skill直接存储在目标应用的代码仓库中。切勿在用户/全局文件夹（如
~/.agents/skills
、
~/.codex/skills
、
~/.claude/skills
或
$CODEX_HOME/skills
）中创建生成的特定于应用的Skill。
通过检查应用仓库选择项目本地存储位置：
  • 如果应用已有项目本地的Skill目录，遵循该惯例。
  • 当仓库使用Claude项目配置时，优先选择
    .claude/skills/<app-name>-production-parity/SKILL.md
    。
  • 当仓库使用Codex项目配置时，优先选择
    .codex/skills/<app-name>-production-parity/SKILL.md
    。
  • 如果没有项目本地的Skill惯例，在创建新惯例前提出一个简洁的harness问题。
  • 如果唯一可用的Skill目录是全局/用户文件夹，请勿使用；询问应将Skill存储在项目仓库的哪个位置。
生成的Skill必须包含：
  • 前端元数据（frontmatter），其描述需触发针对该应用的一致性检查、偏差检测、本地/生产环境不匹配、认证/配置/基础设施差异及环境设置相关操作
  • “应用一致性契约”，将生产环境列为参考标准，并列出有意为之的非生产环境偏差
  • “生产环境事实来源”，包含确切的文件路径、清单、文档、命令或用户确认的来源
  • “检查工作流程”，包含特定于仓库的命令和需读取的文件
  • “一致性维度”，根据应用量身定制，而非通用检查清单的堆砌
  • “偏差检查”，包含Agent应运行的具体测试、脚本、schema或手动检查项
  • “修复模式”，说明如何在该应用的架构中消除偏差
  • “提问协议”，指示Agent使用当前harness的提问工具处理源代码无法解答的决策
  • “输出契约”，规定未来每次运行需输出的内容：检查的文件、发现的风险、已修复的问题、运行的测试、剩余的明确偏差
以
resources/generated-skill-template.md
为基础，但移除无关章节，并将占位符替换为特定于应用的证据。

5. Add Safeguards Where The Repo Supports Them

5. 在仓库支持的地方添加防护措施

If the user asked for fixes, or if the generated skill would be weak without a guard, add narrowly scoped checks in the target app:
  • config parity: schema validation for required env vars and production-only restrictions
  • auth parity: tests for required IdP groups, roles, claims, redirect URIs, cookies, and session policies
  • fixture parity: seeded users, tenants, feature flags, roles, plans, quotas, and data lifecycle states
  • infra parity: parse or diff deployment manifests against local/preview manifests for security-relevant settings
  • provider parity: contract tests or recorded fixtures for external APIs, webhooks, email, storage, queues, and payment providers
  • runtime parity: pinned versions for language runtime, database, extensions, image tags, and build commands
  • smoke parity: a preview/staging smoke test that proves the app starts with production-equivalent restrictions before merge
When a difference is intentional, require a named reason and compensating guard. "Local is easier" is not enough.
如果用户要求修复，或者生成的Skill缺乏防护措施会导致功能薄弱，则在目标应用中添加范围明确的检查：
  • 配置一致性：对必填环境变量和生产环境独有限制进行schema验证
  • 认证一致性：针对必填IdP组、角色、声明、重定向URI、Cookie和会话策略的测试
  • 夹具一致性：已填充的用户、租户、功能标志、角色、套餐、配额和数据生命周期状态
  • 基础设施一致性：解析或对比部署清单与本地/预览清单中的安全相关设置
  • 提供商一致性：针对外部API、Webhook、邮件、存储、队列和支付提供商的契约测试或录制的夹具
  • 运行时一致性：固定语言运行时、数据库、扩展、镜像标签和构建命令的版本
  • 冒烟一致性：预览/预发布环境的冒烟测试，确保应用在合并前以与生产环境等效的限制启动
当存在有意为之的差异时，要求提供明确的理由和相应的防护措施。“本地环境更易用”不足以成为理由。

6. Validate The Generated Skill

6. 验证生成的Skill

Before finishing:
  1. Re-read the generated skill as if invoked on a fresh thread.
  2. Confirm every app-specific claim cites a repo source or a captured user answer.
  3. Confirm no generic checklist item remains unless it applies to the app.
  4. Confirm the generated skill path is inside the target app repository and not in a user/global skills folder.
  5. Run the skill validation command available in the harness or repository if one exists.
  6. If validation cannot be run, say exactly why.
完成前：
  1. 以全新线程调用的视角重新阅读生成的Skill。
  2. 确认每个特定于应用的声明都引用了仓库来源或已记录的用户回答。
  3. 确认未保留任何不适用于该应用的通用检查项。
  4. 确认生成的Skill路径位于目标应用仓库内，而非用户/全局Skill文件夹中。
  5. 如果harness或仓库中有可用的Skill验证命令，运行该命令。
  6. 如果无法运行验证，说明具体原因。

Output

输出

Return:
  • generated skill path
  • confirmation that the generated skill is stored inside the target project repo
  • files and directories inspected
  • highest-risk parity gaps found during creation
  • questions asked and captured decisions
  • tests or validation run
  • recommended next fixes if drift was found but not fixed
Do not present a generic parity report as the final product. The primary deliverable is the reusable app-specific skill.
返回：
  • 生成的Skill路径
  • 确认生成的Skill存储在目标项目仓库内
  • 检查的文件和目录
  • 创建过程中发现的最高风险一致性缺口
  • 提出的问题及记录的决策
  • 运行的测试或验证
  • 如果发现偏差但未修复，推荐后续的修复措施
不要将通用一致性报告作为最终产物。主要交付物是可复用的特定于应用的Skill。