Briefing an AI Agent — Expanded Guide
Before you say “build it”
Treat an AI agent like a very fast senior engineer who has no context, no accountability, and a tendency to fill every gap with a plausible guess.
This guide expands each item on the original checklist with why it matters, concrete examples, the options you can choose from, and what to watch out for. Section 11 gives you a ready-to-paste prompt template.
The problem and the outcome
Agents optimise for the literal request. If you describe a solution instead of a problem, you get that solution — even when a simpler one would have worked.
What problem are you solving?
An agent will happily build the wrong thing, very fast and very well. The problem statement is the only thing that lets it (and you) judge whether a design is good.
“Cut invoice processing from 6 minutes to 30 seconds.” · “Let support agents find the right policy clause in under 10 seconds.” · “Stop reconciliation spreadsheets from drifting out of sync.”
Write it as a job story (“When ___, I want to ___, so I can ___”), a 5-Whys chain, or a cost-of-delay statement. Pick whichever forces a number.
Solution-shaped problems: “build me a RAG chatbot”, “add a Kafka pipeline”. Those are answers, not problems.
Who are the users?
Users determine UX, permissions, error tolerance, and what “good enough” means. A tool for 5 internal analysts and one for 50,000 customers share almost nothing.
Internal ops analysts · external customers · other services (machine users / API clients) · admins · auditors · future maintainers (often forgotten).
Personas, jobs-to-be-done, or simple volume estimates: how many users × how often × how critical.
“Everyone.” If everyone is a user, no one is. Also: naming a user group you’ve never spoken to.
What does success look like — metrics, demo, or production?
The bar determines how much you invest in tests, migrations, observability, and review. A demo and a production system are not the same object.
Demo: works once, on stage, on curated data. MVP: 10 pilot users, no data loss, manual recovery. Production: 99.9% uptime, audit logs, on-call rotation, rollback tested.
Name the tier explicitly and let it drive every other decision. You can always raise the tier later; lowering it after launch is painful.
Prototype funding with production ambition. That mismatch is where most agent-built systems collapse.
What is explicitly out of scope?
An agent with an open scope will build everything it can imagine. Writing down what you are not doing is the cheapest form of control you have.
No mobile app. No SSO in v1. English only. No write-back into SAP. No multi-tenant support. No offline mode. No migration of historical data.
Split into “not now” (deferred, will revisit) and “not ever” (design decision, don’t build for it). The distinction changes the architecture.
Silent scope. If it isn’t written in the repo, the agent will treat it as in scope.
Is this an MVP, prototype, or production system?
This single word changes the definition of done, the test strategy, the deployment target, and how much the agent is allowed to refactor.
Prototype: throwaway, hardcoded data is fine. MVP: real users, real data, but manual ops. Production: SLAs, security review, change control.
If unsure, default to MVP and state the upgrade path. Never default to “production” silently — it multiplies cost.
Prototypes that quietly become production. That is how you end up with no tests and a database nobody can migrate.
Requirements
Functional requirements describe what it does. Non-functional requirements describe how well — and they are usually what actually breaks.
Functional: features, user stories, workflows, edge cases
Agents implement the happy path brilliantly and the edge cases not at all — unless you name them. Edge cases are where the real work lives.
“User uploads a PDF → system extracts fields → user corrects → save.” Edge cases: 40MB file, scanned image, wrong language, duplicate upload, expired session, partial failure mid-save.
Given/When/Then scenarios · user story mapping · a state diagram for any workflow with approvals · a numbered list of edge cases in the repo.
Describing features as nouns (“a dashboard”) instead of behaviours (“a user can see X and filter by Y”).
Non-functional: performance, scale, latency, uptime, security, privacy, accessibility, compliance
These are architecture drivers. “Handle scale” produces a guess; “p95 under 300 ms at 500 concurrent users” produces a design.
p95 latency < 300 ms · 500 concurrent users · 99.9% monthly uptime · WCAG 2.2 AA · data stays in the EU · 10k records/min ingest · recovery in under 1 hour.
Pick the top three that genuinely matter and mark the rest “best effort”. Everything cannot be a priority — and pretending otherwise makes the design incoherent.
“Fast, scalable, secure, and user-friendly” with no numbers. That is a wish list, not a requirement.
Acceptance criteria — how will you know it’s done?
Acceptance criteria are the contract. Without them, “done” becomes a negotiation after the work is finished — and the agent will always claim success.
“When a user uploads a 10 MB PDF, extracted fields appear within 5 s, or a specific error message is shown.” · “A failed job retries three times and then lands in a dead-letter queue with a visible alert.”
Executable tests · a written checklist · a scripted demo path. Executable is best — the agent can run it and self-correct.
Acceptance criteria that only cover the happy path. If it isn’t tested, it isn’t done.
What must never happen?
Invariants are the guardrails you design around. Naming them lets the agent refuse a design that violates them — and lets you place a kill switch.
Cross-tenant data leakage · silent data loss · unauthorised writes to finance systems · PII in logs · unbounded cloud spend · downtime during business hours · irreversible destructive operations.
Write them as a numbered invariant list, add automated checks where possible, and define a manual kill switch and rollback for the rest.
Treating these as “obvious”. They are not obvious to something with no context and no consequences.
Constraints
Constraints are the difference between a design that ships and one that gets rejected in review. State them as rules, not preferences.
Tech stack, language, framework, hosting, cloud, database
An unconstrained agent will pick whatever is most common in its training data — which may be nothing like your environment.
“TypeScript + Node 20, Postgres 15, deployed to AWS eu-west-1, no new SaaS vendors, no ORM beyond Prisma.”
Sort each item into mandated (must), preferred (default unless justified), discouraged (needs a reason), forbidden (never). This prevents the agent from treating a preference as law or a law as a preference.
“Use whatever is best.” That is a licence to add five new dependencies.
Budget, timeline, team size, licenses
These set the shape of the solution. Six weeks and two engineers rules out microservices and a bespoke auth system.
$15k/month infrastructure cap · 6 weeks to pilot · 2 engineers, one part-time · GPL and AGPL banned · existing enterprise licence for X only.
Give a range and a hard ceiling. Say what happens if you exceed it — stop and ask, or absorb it.
Unstated licence rules. An agent will happily add a copyleft dependency to a commercial codebase.
Existing systems, APIs, data sources, legacy code
Integrations are usually the largest source of delay. Legacy systems are where “simple” projects go to die.
A legacy SOAP endpoint with no sandbox · a nightly CSV drop at 02:00 · an ERP with no test environment · a Python 2 script nobody wants to touch · an API with a 10 requests/minute limit.
For each system, state: protocol, auth method, rate limit, environment availability, owner, and whether you may modify it.
“It should integrate with our systems.” Name them. All of them.
Deployment environment: local, staging, production
The agent needs to know where it may run things. Deploying to production without asking is a common and expensive failure mode.
Local Docker Compose · ephemeral preview environment per branch · staging that mirrors production · production behind a change-approval gate.
State explicitly which environments the agent can touch, and which require a human. Default: local and preview yes, staging on request, production never.
Shared credentials that let an agent reach production by accident.
Legal and regulatory constraints: GDPR, HIPAA, SOC 2, etc.
Compliance determines data handling, retention, audit trails, vendor choice, and where data may physically sit. Retrofitting it is extremely costly.
GDPR data-subject requests and lawful basis · HIPAA BAA and PHI handling · SOC 2 evidence and access reviews · PCI scope avoidance by never touching card data.
Name the regime, the owner, and the evidence required. If unsure, say “unknown — treat as regulated until confirmed”.
Sending regulated data to a third-party API “just for testing”.
Architecture and interfaces
You do not need to design everything up front. You do need to fix the shape, the contracts, and the boundaries — because those are the expensive things to undo.
High-level shape
Shape determines deployment, testing, failure modes, and team structure. It is the single hardest decision to reverse.
Monolith · modular monolith · microservices · serverless functions · event-driven pipeline · scheduled batch job · CLI tool · web app · internal API.
Default to a modular monolith unless you have a concrete reason: independent scaling, separate teams, or genuinely different runtime needs. Serverless suits spiky, event-driven workloads; microservices suit organisational scale, not technical elegance.
Microservices chosen by default. They multiply operational cost and are the most common over-engineering an agent will happily produce.
Data model, schemas, storage, migrations
Data outlives code. A bad schema is a decade-long tax; a good migration practice is what lets you change your mind safely.
Entities and relationships · primary keys (UUID vs serial) · soft vs hard deletes · timestamps and timezones · migration tooling (Prisma, Flyway, Alembic, Django migrations) · forward-only migrations.
Relational (Postgres) for structure and transactions · document store for variable shapes · object storage for files · search index for text. Pick one primary store and justify any addition.
Destructive migrations with no backup. Tell the agent: never drop a column or table without explicit approval.
External APIs and integration contracts
Contracts are where systems agree. If they are implicit, every integration becomes a debugging session.
An OpenAPI spec in the repo · webhook signature verification · idempotency keys on retries · exponential backoff with jitter · timeout and circuit-breaker rules · a documented sandbox.
Contract-first (write the spec, generate stubs) vs code-first (generate the spec from code). Contract-first is better when a third party is involved.
Agents inventing API endpoints and field names that look plausible. Verify every external call against real documentation.
Auth, roles, permissions
Auth is the highest-consequence code in the system and the easiest to get subtly wrong. It deserves explicit rules and human review.
OIDC / SSO with your identity provider · RBAC (roles → permissions) · ABAC (attribute rules) · service accounts with scoped tokens · tenant isolation enforced at the query layer · break-glass admin with audit.
Buy auth (Auth0, Clerk, Cognito, Keycloak) unless you have a strong reason to build it. Building auth is a classic agent over-reach.
Rolling your own password hashing, session handling, or JWT validation. Mark auth as a stop-and-ask area.
Dev/staging/prod separation, secrets management, CI/CD
This is the machinery that makes change safe. Without it, every deploy is an event rather than a routine.
Secrets in a vault or platform secret store, never in the repo · environment variables per environment · GitHub Actions / GitLab CI pipelines · preview environments per pull request · blue/green or canary deploys · one-command rollback.
Start with the simplest pipeline that runs tests and deploys to staging. Add preview environments and progressive delivery only when the team feels the pain.
An agent committing a .env file, or writing secrets into logs and test fixtures.
Security and risk
An agent has no instinct for danger. It will write a working feature that leaks data, because nothing in its training tells it that this particular field is sensitive.
What data is sensitive?
You cannot protect what you have not named. Classification drives encryption, logging rules, retention, and which third parties may ever see it.
PII (names, emails, addresses) · PHI · credentials and tokens · payment data · source code · internal pricing and margins · employee records · customer contracts.
Three-tier classification is usually enough: public, internal, restricted. State the handling rule for each tier.
“It’s only test data.” Test data copied from production is production data.
Who can access what?
Access rules are the difference between a feature and a breach. They must be written down, not inferred from the UI.
A role × resource matrix · least privilege by default · tenant isolation · admin actions logged · read vs write vs delete separated · no shared accounts.
RBAC for simple orgs, ABAC for fine-grained rules, or a hybrid. Whatever you choose, enforce it server-side — never in the client.
Authorisation checks that live only in the frontend, or an admin endpoint with no role check because “only admins know the URL”.
Encryption, audit logs, backups, threat model
These are the controls that limit damage when something goes wrong — and something will go wrong.
TLS 1.3 in transit · AES-256 at rest · immutable append-only audit trail · 3-2-1 backups with a tested restore · STRIDE or a simple “what could go wrong” list · secret rotation.
Full threat modelling is overkill for an MVP. A one-page list of the top five risks and their mitigations is not.
Backups that have never been restored. An untested backup is a hope, not a control.
Dependency and supply-chain risk
Agents add packages freely, and package names are a favourite target for typosquatting and malicious releases.
Committed lockfiles · pinned versions · automated dependency scanning (Dependabot, Renovate, Snyk) · an SBOM · no install scripts from unvetted packages · a short allow-list of approved libraries.
Strict allow-list (safest, slowest) · blocklist plus review (balanced) · open with automated scanning (fastest, riskiest). Choose based on how regulated you are.
A package that exists but is a near-name match for a popular one. Always verify the package actually exists and is the one you meant.
What the agent is not allowed to do
This is your hard boundary list. Without it, an enthusiastic agent will deploy, delete, spend, and call third parties — all in good faith.
No deploying to production · no destructive SQL (DROP, TRUNCATE, unbounded DELETE) · no spending money or provisioning paid resources · no calling external services with real data · no installing packages without approval · no touching auth, payments, or billing · no sending data to third parties · no force-pushing or rewriting shared history.
Express each as: forbidden (never), ask first (needs approval), allowed with logging. Then enforce the important ones technically, not just in prose.
Relying on the prompt alone. A written rule plus a scoped credential is far stronger than a written rule by itself.
Quality bar
The quality bar is how you convert “looks done” into “is done”. It is also where you decide how much rope to give the agent.
Definition of done
Agents stop when the code runs. Your definition of done is usually several steps further on.
Code written · tests passing · lint and type checks clean · docs updated · PR reviewed by a human · deployed to staging behind a feature flag · acceptance criteria demonstrated.
Write it as a literal checklist in the repo. The agent can then tick it off, and you can see what it skipped.
“Tests pass” as the whole definition. Tests written by the same agent that wrote the code prove less than you think.
Test strategy: unit, integration, end-to-end
Tests are how the agent verifies its own work without you. The right mix depends on where your risk lives.
Unit tests for pure logic · integration tests against a real database · contract tests for external APIs · end-to-end tests for critical journeys · golden-file tests for parsers · property-based tests for tricky formats.
Classic pyramid (many unit, fewer integration, few E2E) for most apps · the testing trophy (integration-heavy) for frontend and API work · golden files for anything that transforms documents.
Tests that assert the implementation rather than the behaviour — they will pass while the feature is broken.
Linting, type checking, formatting, code review
Automated style and type checks remove an entire category of review noise, so humans can review logic instead of formatting.
ESLint / Ruff · Prettier / Black · TypeScript strict mode / mypy / Pyright · pre-commit hooks · CI gates that block merge on failure · a required human reviewer for sensitive paths.
Strict from day one (cheaper long-term) vs relaxed for a prototype. Whatever you choose, make it automatic — manual standards get ignored at speed.
The agent disabling a lint rule or adding # type: ignore to make CI pass. Explicitly forbid that.
Documentation expectations
Documentation is the context the next session — human or agent — will rely on. It is also the cheapest way to make an agent effective.
A README quickstart that actually works · ADRs for significant decisions · a runbook per alert · API docs · “why” comments for non-obvious code · a CHANGELOG.
Minimum viable: README + decisions log + runbook. Add the rest only when someone actually needs it.
“We’ll document it later.” Later never comes, and the agent loses the context it needs to help.
How much autonomy does the agent have?
Autonomy is a dial, not a switch. Setting it explicitly prevents both paralysis and runaway changes.
L0 suggest only, no file writes · L1 write code on a branch · L2 open pull requests for review · L3 merge to main behind feature flags · L4 deploy to production autonomously.
Start at L1–L2. Earn L3 with a track record and strong tests. Treat L4 as an explicit, temporary, well-monitored exception — if ever.
Jumping to L3 or L4 on day one because the output looked good in a demo.
Operations
Operations is everything that happens after the code works. It is the most commonly skipped section and the most common reason a project is quietly abandoned.
How will it be deployed?
Deployment shapes the code. A container on a platform is a different design from a zip uploaded to a VM.
Container image to a managed platform · serverless functions · a VM with a systemd service · infrastructure as code with Terraform or Pulumi · a pipeline that builds, tests, and promotes.
Managed platform (fastest, least control) · containers on a cloud runtime (balanced) · self-managed VMs or Kubernetes (most control, most cost). Match the choice to team capability.
Manual deployment steps in someone’s head. If it isn’t scripted, it isn’t repeatable.
Monitoring, logging, alerting, rollback
You cannot operate what you cannot see. And you cannot move fast without a fast way back.
RED metrics (rate, errors, duration) · structured JSON logs with request IDs · error tracking with Sentry or equivalent · alerts on SLO burn rate, not raw CPU · a tested one-command rollback · feature flags to disable without deploying.
Start with error tracking plus one uptime check. Add dashboards and SLOs when you have real traffic — not before.
Alerts that fire constantly and get ignored. Every alert should have an owner and a runbook.
Backup/restore, runbooks, on-call
These determine how bad a bad day gets. A tested restore turns a catastrophe into an inconvenience.
Automated daily backups · a restore rehearsed every quarter · a runbook per alert · an escalation policy · a documented maintenance window.
No formal on-call for an MVP is fine — as long as someone is named and reachable, and the risk is written down and accepted.
Assuming a managed service removes the need for backups. It reduces the risk; it does not remove the responsibility.
Who owns it after the agent stops?
The agent will not be on call. Ownership is the hand-off that keeps the system alive after the build phase ends.
A named team in the service catalogue · an on-call rotation · a maintenance budget · an agreed deprecation or upgrade path.
Assign ownership before launch, not after. If nobody will own it, that is a signal the project may not be worth building.
“The project team will support it” — when the project team is one contractor and an AI.
AI-agent-specific working agreement
This section is unique to working with agents. These practices are what separate a productive agent session from an expensive mess.
Give it a repo, not just a chat
Chat history is ephemeral, length-limited, unversioned, and invisible to your team. A repository is persistent, reviewable, and shared.
Work in a Git branch · commit the agent’s changes with meaningful messages · keep the task description as a file in the repo.
Chat-only for throwaway questions · repo-based for anything that will be reviewed, deployed, or maintained.
Copy-pasting code out of a chat window into your codebase with no history and no review.
Put specs, diagrams, and decisions in files the agent can read
Every file in the repo is context the agent can retrieve on demand. This is how you avoid re-explaining the project every session.
AGENTS.md or CLAUDE.md with the working agreement · docs/adr/ for decisions · ARCHITECTURE.md with a diagram · CONTRIBUTING.md with conventions · a task file with a checklist.
Minimum: one AGENTS.md plus a task file. Expand as the project grows.
Critical context that exists only in someone’s head or in a Slack thread.
Ask it to plan first, then implement in small increments
A plan is cheap to review and cheap to correct. A thousand-line diff is neither. Planning also surfaces misunderstandings before they are encoded.
“First give me a plan: files to change, approach, tests, and risks. Wait for approval.” Then: “Implement step 1 only. Stop and report.”
One step per commit · one step per PR · or one step per session. Smaller is safer, slightly slower, and much easier to debug.
“Build the whole thing.” You will get a large, plausible, unreviewable diff.
Require tests before or alongside code
Tests are how the agent checks its own work without you in the loop. Without them, “it works” is an assertion, not evidence.
“Write a failing test first, then make it pass.” · “Add an integration test against the real database.” · “Show me the test output.”
Strict TDD · tests alongside code · tests at the end of each step. Any of these beats “we’ll add tests later”.
Tests that were written to match the buggy behaviour. Read the assertions, not just the green check.
Require it to ask clarifying questions when ambiguous
By default, agents resolve ambiguity silently and confidently. You want the ambiguity surfaced while it is still cheap.
“Before starting, list any ambiguities and ask up to five questions. If nothing is ambiguous, say so explicitly and proceed.”
Always ask · ask only when the decision is irreversible · proceed with stated assumptions. The middle option is usually the best balance.
“Proceed with your best judgement” on high-stakes decisions. That is how you get a schema you did not agree to.
Set stop conditions
Stop conditions are the circuit breakers. They keep the agent inside the blast radius you have actually approved.
Stop and ask before: adding a dependency · changing the database schema · touching auth, payments, or billing · modifying CI/CD or secrets · changing public API contracts · editing more than N files · deleting anything · any irreversible action.
Write them as a numbered list in AGENTS.md and restate them at the top of each session. Repetition works.
Stop conditions that exist only in a chat message the agent will eventually forget.
Keep context in the repo
Long sessions degrade. Context windows fill, early instructions get summarised away, and the agent starts contradicting decisions you made an hour ago.
A decisions log · a task checklist with status · a “current state” section in the README · one session per milestone rather than one endless thread.
Short sessions with a written brief each time · long sessions with periodic “write what we decided into the repo” checkpoints. Both work; the second requires discipline.
Trusting that the agent remembers an instruction from two hours ago. If it matters, put it in a file.
Verify dependencies, APIs, licences, and security claims — it can hallucinate
Confident, plausible, and wrong is the default failure mode. Hallucinated packages and API signatures are common and can be a supply-chain risk.
A package name that does not exist · a real package with a similar name (typosquatting) · a function signature that changed two versions ago · a licence that conflicts with your policy · a CVE in a suggested version.
Check the registry before installing · run the code, don’t just read it · read the actual docs for external APIs · scan dependencies automatically. Treat every claim as unverified until demonstrated.
“This library handles it.” Ask which library, which version, and where the documentation is.
You own the output — the agent cannot take responsibility
This is the single most important line in the whole document. There is no accountability on the other side of the prompt.
You sign the PR. You approve the deploy. You answer to the customer, the auditor, and the regulator. The agent will not be in that meeting.
Adjust autonomy to match how much you can genuinely review. If you cannot review it, do not let it merge.
“The AI wrote it” as an explanation. It is not a defence, and it is not a review.
Governance
Governance is who decides what, and what happens when the agent is stuck. It takes ten minutes to set up and saves weeks of drift.
Who is the product owner? Who is the tech lead?
Split the “what and why” from the “how”. Without this split, scope and architecture arguments get confused with each other.
Product owner: owns outcomes, scope, priorities, and acceptance. Tech lead: owns architecture, standards, and technical trade-offs.
One person can hold both roles on a small project — as long as everyone knows which hat is on.
No named owner. Shared ownership of a decision is usually no ownership.
Who approves architecture, security, and scope changes?
Changes will happen. Pre-deciding who approves them turns a political fight into a process step.
Architecture changes → tech lead. Security-relevant changes → security owner. Scope changes → product owner. Anything touching regulated data → compliance owner.
Lightweight (one approver per domain) vs formal (review board). Match to your risk and organisation size.
Approval by silence. If nobody objects, that is not the same as approval.
How are changes handled?
A consistent change path keeps the repo readable and the history trustworthy — especially when an agent is producing most of the commits.
An ADR for significant decisions · a pull request per change · a changelog · release notes · a decision log the agent must update.
Full ADR process · a simple “decisions.md” append-only log · commit messages only. Pick one and be consistent.
Decisions made in chat and never written down. The next session will not know they happened.
What is the escalation path when the agent is stuck or wrong?
Agents can loop: retrying the same broken approach, or confidently producing worse and worse fixes. A timeboxed escalation stops the bleeding.
After 3 failed attempts on the same issue, stop and summarise what was tried · escalate to the tech lead · if unresolved in 30 minutes, escalate to the product owner to reconsider scope.
Time-based (N minutes) · attempt-based (N tries) · confidence-based (agent must state confidence and stop below a threshold). Attempt-based is easiest to enforce.
Letting it retry indefinitely. Loops burn time and often make the code worse with each pass.
Minimum brief before you start
If you only write one page, write this. Ten items. Everything else is detail.
- Problem and users.Who hurts, how much, and why now.
- Success criteria and non-goals.How you will measure it, and what you are explicitly not doing.
- Core features and edge cases.The happy path plus the awkward cases that will actually break it.
- Tech constraints and preferred stack.Mandated, preferred, discouraged, forbidden.
- Data sources and integrations.Systems, protocols, owners, limits, environments.
- Security and privacy requirements.What is sensitive, who can see it, what must never happen.
- Acceptance tests.Executable where possible, written otherwise.
- Deployment target.Local, staging, production — and what the agent may touch.
- What the agent may and may not do.Forbidden, ask-first, allowed-with-logging.
- Review gates.Who approves, what triggers a stop, how to escalate.
The perfect prompt
A complete briefing template. Replace every [bracket] with your specifics,
delete sections that genuinely do not apply, and put the result in the repo as
AGENTS.md so every session starts from the same context.
# ROLE You are a senior software engineer working inside this repository. You have no prior context about this project other than what is written here and what you read in the repo. You cannot take responsibility for the outcome — I can. So follow this brief exactly, and ask before you do anything that is not covered by it. # 1. CONTEXT Product: [name / one-line description] Problem we solve: [the real problem, with a number if possible] Users: [who they are, roughly how many, how often they use it] Why now: [the trigger — deadline, regulation, outage, growth] Stage: [prototype | MVP | production] Success metrics: [metric 1 with baseline and target, metric 2, ...] Out of scope: [explicit list — "not now" and "not ever"] # 2. REQUIREMENTS Functional: - [feature / user story 1] - [feature / user story 2] - [workflow with states, if any] Edge cases that must be handled: - [e.g. oversized file, empty input, duplicate submission, partial failure] - [e.g. external API timeout, malformed response, rate limit hit] - [e.g. concurrent edits, stale session, permission denied] Non-functional (only the ones that actually matter): - Performance: [e.g. p95 under 300 ms at 200 concurrent users] - Reliability: [e.g. 99.5% monthly uptime, automatic retry with backoff] - Security: [e.g. all access server-side, least privilege, audit log] - Privacy: [e.g. no PII in logs, data stays in EU] - Accessibility: [e.g. WCAG 2.2 AA for the main flow] Acceptance criteria (how we know it is done): - [criterion 1 — observable and testable] - [criterion 2] Invariants — these must NEVER happen: - [e.g. cross-tenant data leakage] - [e.g. silent data loss] - [e.g. unauthorised writes to an external system] - [e.g. unbounded cloud spend] # 3. CONSTRAINTS Mandated: [language, runtime, framework, database, cloud, region] Preferred: [default choices unless there is a strong reason] Discouraged: [needs justification to use] Forbidden: [never use — e.g. GPL/AGPL deps, new SaaS vendors] Budget/time: [infra budget per month, deadline, team size] Existing: [systems, APIs, data sources, legacy code we must live with] Environments: [local | preview | staging | production — and which I may touch] Compliance: [GDPR / HIPAA / SOC 2 / PCI / none known] # 4. ARCHITECTURE Shape: [modular monolith | services | serverless | batch | CLI | web app] Data: [primary store, key entities, migration tool, retention rules] Integrations: [each external system: protocol, auth, rate limit, sandbox availability] Auth: [identity provider, roles, permission model, tenant isolation] Delivery: [CI/CD, secret management, deploy strategy, rollback method] # 5. SECURITY Sensitive data: [what it is, and which classification tier] Access rules: [who can read/write/delete what] Controls required: [encryption in transit/at rest, audit log, backups, threat model] Supply chain: [lockfiles, pinned versions, scanning, allow-list of packages] # 6. QUALITY BAR Definition of done: 1. Code implemented and committed on a feature branch 2. Tests written and passing 3. Lint, format, and type checks clean 4. Docs updated (README / decisions log / runbook as relevant) 5. Pull request opened with a summary and a test plan 6. Acceptance criteria demonstrated, not asserted Testing: [unit / integration / contract / e2e mix, and what must be covered] Conventions: [linter, formatter, type checker, commit message style] Docs: [what to write and where] Autonomy level: [L1 branch only | L2 open PRs | L3 merge behind flags | L4 deploy] Never disable a lint rule, type check, or test to make something pass. If one is genuinely wrong, stop and tell me instead. # 7. OPERATIONS Deploy: [how it ships, and who triggers it] Monitoring: [metrics, logs, error tracking, alerting] Rollback: [how to revert, and how fast] Ownership: [who owns this after the build phase] # 8. WORKING AGREEMENT 1. Read the repo before writing anything. Read AGENTS.md, README, docs/, and the existing code style. Match what is already there. 2. Plan before you build. Produce: files to change, approach, tests, risks, and open questions. Then STOP and wait for my approval. 3. Implement in small increments. One logical step per commit. After each step, report what changed and what you verified. 4. Write tests alongside or before the code. Run them. Show me the output. 5. Ask when ambiguous. Before starting, list any ambiguities and ask up to five questions. If nothing is ambiguous, say so explicitly and proceed. 6. Keep context in the repo, not in chat. Record decisions in docs/decisions.md and keep the task checklist up to date. 7. Verify every external claim. Confirm that packages exist, that API signatures are real, and that licences are acceptable. Do not trust your own recall. 8. Update documentation as part of the work, not afterwards. STOP AND ASK BEFORE: - Adding any new dependency - Changing the database schema or running a migration - Touching authentication, authorisation, payments, or billing - Modifying CI/CD, secrets, or infrastructure configuration - Changing a public API contract - Deleting or renaming files outside the current task - Changing more than [N] files in one step - Any action that is irreversible or spends money NEVER: - Deploy to production - Run destructive SQL (DROP, TRUNCATE, unbounded DELETE) - Provision paid resources or call paid external APIs - Send real data to any third party - Commit secrets, tokens, or credentials - Force-push or rewrite shared history - Disable or skip a failing test, lint rule, or type check to make progress ESCALATION: - If the same problem fails 3 times, stop, summarise what you tried, and ask. - If a requirement is contradictory or impossible, stop and say so. - If you are uncertain about a decision with lasting consequences, stop and ask. - Do not guess your way past a blocker. Report it. # 9. FIRST TASK [Describe the smallest valuable slice here. Example: "Implement a single endpoint that accepts a PDF upload, extracts the invoice number and total, and returns them as JSON. No database, no UI, no auth. Include unit tests for the parser and one integration test."] Start by giving me your plan. Do not write code until I approve it.