Repository AGENTS.md テンプレート
このページは、記入用テンプレートを誤ってサイトのメタデータとして解釈しないよう、原文をコードとして表示しています。
# Repository operating contract
<!--Copy this file to the repository root as AGENTS.md.Delete examples that are not true. Never leave invented commands or paths.Keep this file short; link to versioned details instead of pasting them here.-->
## Mission and source of truth
- Product outcome: `<<required: one sentence describing the customer outcome>>`- Architecture: `<<required: path to architecture/index document>>`- Product decisions: `<<required: path to task/spec or product docs>>`- Delivery evidence: `<<required: path convention, e.g. docs/delivery/CHG-*/>>`- Security/privacy baseline: `<<required: path>>`- Runbooks: `<<required: path>>`
If code, docs, generated artifacts, and external contracts disagree, report the conflict. Do not silently choose the easiest interpretation.
## Repository map
- `<<required: path>>`: `<<required: responsibility>>`- `<<required: path>>`: `<<required: responsibility>>`- `<<required: path>>`: `<<required: responsibility>>`
Keep domain rules separate from provider/UI adapters. Name generated and vendored directories that must not be edited manually.
## Exact commands
Run commands from `<<required: repository root or named directory>>`.
- Install: `<<required: reproducible install command>>`- Development: `<<required: dev command>>`- Format check: `<<required: command>>`- Lint: `<<required: command>>`- Typecheck/build: `<<required: command>>`- Unit tests: `<<required: command>>`- Integration tests: `<<required: command and prerequisites>>`- E2E/revenue-critical tests: `<<required: command and prerequisites>>`- Security/dependency check: `<<required: command or N/A with reason>>`- AI eval: `<<required: command or N/A with reason>>`
Do not claim a check passed without running the exact applicable command. Report command, exit status, failed/skipped/flaky cases, and environment limitations.
## Durable invariants
<!-- Keep only consequential, non-obvious repository invariants. -->
- Every tenant-owned read and write is server-side scoped to the authenticated tenant; never trust a client-provided tenant ID by itself.- Billing, webhook, job, and external write handlers are idempotent and preserve an append-only audit key.- Secrets, credentials, payment data, and unnecessary customer content never enter source, logs, analytics, fixtures, prompts, or screenshots.- Public API/event names and persisted schemas do not change without an explicit compatibility and migration plan.- Production side effects use test credentials or a sandbox during development; never send, charge, publish, delete, or mutate production data without explicit authorization.- `<<required: add 0–3 product-specific invariants, or delete this line>>`
## Change triggers
- Important architecture, provider, public contract, or irreversible choice: create/update an ADR.- New trust boundary, permission, sensitive data flow, dependency, external write, or migration: update the threat-model delta.- Behavior or AI configuration change: map acceptance criteria to tests/eval cases and record an exact evidence snapshot.- Production change: record immutable artifact, rollout, monitors, stop conditions, rollback class, owner, and post-release observation time.- Runtime identity/IAM, DB role/RLS/grants, credential ID-version-scope, egress, or autonomous trigger change: bind intended authority in review/deploy manifests and verify the actual authority receipt before enabling ingress/effects.- Auth/tenant/billing/personal-data/migration/privileged-CI/important-dependency/AI-tool-effect/rollback-weakening paths: derive at least R2 and required evidence from the semantic manifest. An applicable trigger's minimum tier/evidence is non-waivable. A lower reclassification is allowed only after positive evidence proves a false positive or the triggering scope is removed and the scan is rerun; owner approval alone is insufficient.
Use `<<required: task template path>>` and keep the same `change_id` across evidence within one delivery bundle. An incident always opens a new response `change_id` and links `originating_change_ids` plus affected release manifests.
## Scope and change discipline
- One task produces one coherent customer or operational outcome.- Preserve unrelated user changes and do not reformat, rename, refactor, or add dependencies outside the stated scope.- New production dependencies require identity, maintenance, license, install-script, transitive-risk, size/cost, and removal-path review.- Changed or release-relevant privileged producer/consumer/deployer jobs require trigger, actor/ref trust, runner, token permissions, secret/OIDC, network/write targets, and artifact handoff review. Never combine untrusted code/artifacts with a privileged context.- Do not modify migrations, auth, billing, tenant boundaries, public APIs, policy, or production configuration as an incidental fix.- If an assumption changes the requested outcome or risk boundary, mark it `UNKNOWN` and surface it before proceeding.
## Verification by impact
| Changed area | Required minimum evidence ||---|---|| Pure domain rule | unit/property tests including boundary and counterexample || DB/query/migration | integration, tenant-negative, forward migration, reconciliation, rollback/compensation evidence || API/webhook/job | contract, auth/signature, duplicate, reverse-order, retry/timeout tests || UI | loading, empty, error, permission, keyboard/accessibility, responsive behavior || Billing | signature, idempotency, amount/currency/tax, failure/recovery, cancellation/refund || AI model/prompt/retrieval | frozen cases/splits/versions, critical failures, x/n and unknown, cost/latency || Tool action | exact approval, target/args, post-condition, duplicate execution, cancel/rollback || Operations | metrics/logs without secrets, alert action, runbook, stop and recovery verification |
Select applicable rows and explain exclusions. A checkbox is not evidence.
## Code Review Rules
<!--Write each rule as invariant + scope + safe path. Keep mechanical formatting in CI.Add a trigger example, a safe counterexample, and an unrelated counterexample when testing a new rule.-->
### Tenant isolation
- Flag any tenant-owned query or cache key that can execute without server-derived tenant scope. Safe path: derive tenant context from the authenticated session and test another-tenant IDs return no data and make no mutation.
### External effects
- Flag send/pay/publish/delete/write paths that lack an idempotency key, bounded authority, audit event, and verified post-condition. Safe path: separate propose from commit, require exact approval where appropriate, and make retry safe.
### Compatibility
- Flag removal or rename of documented public APIs, events, fields, persisted values, or migrations without a compatibility plan. Safe path: preserve the old contract during a measured migration or version the interface.
### Customer data
- Flag logs, fixtures, prompts, analytics, or errors that add credentials, payment data, personal data, or unnecessary customer content. Safe path: minimize, redact, use synthetic fixtures, and record controlled artifact references instead of raw content.
## Definition of done
- The stated behavior and non-goals match the diff.- Every applicable `AC-*` points to current evidence for the exact commit.- Test/eval results have one immutable `EVID run manifest`; PR and release refer to its hash instead of retyping PASS counts.- Reviewed head, merge/source tree, build provenance, artifact, schema/intended config/tool policy, IaC, runtime identity/IAM, DB role/RLS/grants, credential ID-version-scope, and egress reach an approved deploy manifest before suspended stage-0 deploy.- A trusted upstream fence receipt disables candidate traffic/webhook/queue/cron/startup/tool-effect surfaces before the candidate starts; customer exposure 0 alone is insufficient.- The actual runtime/authority receipt matches that deploy manifest and reaches a separately approved promotion manifest before any candidate ingress/effect is enabled or released/exposed.- Every enable/expansion has a trusted activation receipt whose actual cohort, ingress/effect capability, controller version, and residual fences match the fresh approval before the stage is considered active.- Relevant format, type, lint, test, security, eval, and generated-diff checks pass; failures/skips/unknowns are disclosed.- Data, permission, privacy, cost, dependency, compatibility, migration, observability, and rollback impacts are reviewed.- User-visible behavior, API, operations, or decisions update the corresponding documentation/runbook.- No required `STOP`, `PAUSE`, or `UNKNOWN` remains before a `SHIP` decision.- The final handoff lists changed files, evidence, remaining risk, and next observation time.
Codex completion is not production authorization. Merge, deploy, exposure, risk acceptance, and destructive/external actions remain subject to repository controls and accountable human approval.