An AI coding agent can produce a clean diff for the wrong problem faster than a team can review it. The expensive failure is often not bad syntax. It is task drift: the agent inferred a different user, optimized an unobserved behavior, expanded a small request into a framework, or consumed the available work session before anyone agreed on what “done” meant.
A No-Code First Checkpoint is a short gate before implementation. During this checkpoint, the agent may inspect the repository, read existing documentation, examine supplied logs and screenshots, and ask focused questions. It may not write code, install dependencies, edit configuration, change data, or use Git. The gate opens only after a compact problem record exists.
This is not a claim that planning guarantees success. It does not. The checkpoint only improves the odds that implementation starts with a shared, testable target. Code review, tests, security controls, and human judgment still matter. Pair it with How to Review AI-Generated Code after implementation and Machine Gates for AI Output where a deterministic check can enforce the result.
Facts, anecdotes, and recommendations
This guide keeps three kinds of evidence separate:
- Official fact: a current product document or standards-body source directly supports the statement.
- Anecdotal demand evidence: a public post reports one person’s experience or preferred workaround. It shows a pain worth investigating, not a product-wide rate or guaranteed outcome.
- Recommendation: the workflow in this article. It is a practical synthesis to test in your own repository, not an official Anthropic, OpenAI, GitHub, ISO, IEEE, NIST, IETF, or W3C method.
Official product features make a read-first phase possible. Anthropic documents a Claude Code plan mode that reads files, explores with shell commands, and proposes changes without editing source until approval. OpenAI documents a Codex read-only mode for chatting or planning without changes, and states that non-interactive codex exec uses a read-only sandbox by default. These are product capabilities, not proof that every team needs the checkpoint described here. See the official Claude Code permission modes, Claude Code common workflows, Codex approvals and security, and Codex non-interactive mode.
The first checkpoint contract
The checkpoint begins before the first implementation action. The agent can gather evidence, but it cannot alter the system it is trying to understand.
Use this exact boundary:
Until the checkpoint record is complete, inspect and ask questions only. Do not write or modify code, tests, generated files, documentation, configuration, lockfiles, dependencies, databases, or production data. Do not install or update anything. Do not use Git, including read-only Git commands. Do not publish, deploy, send, purchase, or call a mutating external tool.
The “no Git” rule is intentionally stricter than many planning modes. It avoids hidden hooks, aliases, filters, credential helpers, repository locks, and accidental branch or index operations. File reads and directory listings are enough for the first pass. If commit history is essential evidence, record that need as a constraint and make the first approved implementation-stage action a narrowly scoped Git inspection.
The record is complete only when all fields below contain a concrete answer. “Unknown” is allowed when it is meaningful, but it must include the cheapest safe way to resolve the unknown.
| Required field | Question the record must answer | Minimum acceptable evidence |
|---|---|---|
| Problem | What decision or behavior is wrong? | One sentence describing the failure, not a proposed solution |
| Affected user | Who experiences the problem, in what context? | A role, task, environment, and relevant access level |
| Observable current behavior | What happens now? | Reproduction steps, a supplied log, a screenshot, a query result, or an explicit “not yet reproduced” |
| Desired behavior | What should the user observe instead? | A visible outcome stated without choosing an implementation |
| Constraints | What boundaries cannot be crossed? | Compatibility, security, privacy, latency, cost, deadline, ownership, and allowed files as applicable |
| Non-goals | What tempting adjacent work is excluded? | At least one explicit exclusion for any task with expansion risk |
| Evidence | Why do we believe this is the problem? | Source, timestamp, environment, and confidence level |
| Acceptance test | How will a reviewer decide pass or fail? | A repeatable setup, action, and expected result |
| Rollback | How will the change be reversed or contained? | Revert unit, backup/restore path, feature switch, or documented manual recovery |
| Stop condition | When must the agent pause rather than continue? | A measurable trigger such as scope expansion, missing access, conflicting evidence, or test failure |
The checkpoint record is written outside the implementation surface: an existing issue, task system, run transcript, or chat response. Creating or editing a repository issue-form template is itself a configuration change and therefore belongs after the gate. If the task arrives through an existing GitHub issue form, the agent can use the submitted fields as input and fill only the missing checkpoint fields in its response.
This structure complements an operational repository guide. How to Write an AGENTS.md File That Coding Agents Can Follow explains where persistent commands and boundaries belong. The checkpoint is task-specific; AGENTS.md is repository-specific. Do not copy one into the other.
Why these fields are not arbitrary
Official fact: ISO/IEC/IEEE 29148:2018 describes requirements-engineering processes and the information items produced by those processes. ISO’s page says the standard applies across products, services, methodologies, project sizes, and complexity levels, and notes that the 2018 edition was confirmed in 2024 while a revision is being developed. This article does not reproduce the paid standard; it uses the public abstract only. See ISO/IEC/IEEE 29148:2018.
Official fact: ISO 9241-210:2019 provides requirements and recommendations for human-centred design throughout the life cycle of interactive systems. NIST’s human-centred design summary emphasizes understanding users, tasks, environments, and user requirements before producing and evaluating design solutions. That is why “affected user” and “desired behavior” are separate from the implementation idea. See ISO 9241-210:2019 and NIST Human Centered Design.
Official fact: ISO/IEC 25010:2023 defines a product quality model intended to support requirements, test objectives, quality-control criteria, and acceptance criteria. It does not say that one universal metric fits every product. See ISO/IEC 25010:2023. NIST’s public requirements-verification page lists qualities such as completeness, consistency, traceability, unambiguity, understandability, and verifiability. Those qualities explain why “make it better” is not an acceptance test. See NIST Requirements Verification Tools.
Official fact: NIST’s Common Industry Specification for Usability Requirements describes three kinds of information: context of use; performance and satisfaction criteria; and the test method and context for evaluating those criteria. See NISTIR 7432. This guide translates that idea into a lightweight software-task record; it does not claim formal conformance.
When the checkpoint helps and when it adds friction
Do not turn every typo into a ceremony. The checkpoint earns its cost when a wrong first move is more expensive than a short clarification.
| Task signal | Use the full checkpoint? | Why |
|---|---|---|
| A production bug is reported without reliable reproduction | Yes | The symptom, affected user, and desired behavior can easily be confused |
| A request names a solution but not the user problem | Yes | It exposes whether the requested mechanism is necessary |
| Data will be deleted, merged, transformed, or backfilled | Yes | Evidence, dry-run acceptance, rollback, and stop conditions are essential |
| Authentication, authorization, payments, privacy, or external side effects are involved | Yes | The cost of a wrong assumption is high |
| More than one package, service, or owner may be affected | Yes | Non-goals and ownership boundaries prevent task drift |
| A time-sensitive incident is active | Yes, compressed | Spend three to five minutes recording all fields; prioritize containment and stop conditions |
| A one-line copy correction has an exact file and exact replacement | Usually no | The outcome is already observable and rollback is trivial |
| A formatter-only change has a deterministic command and no semantic effect | Usually no | The tool output is the acceptance test |
| A failing test names one expected literal and the requested change is exact | Use a micro-checkpoint | Confirm the failure is intended, then implement |
| The checkpoint would take longer than the safe, reversible task | No | Record only scope, acceptance, and rollback in the implementation prompt |
The friction test is simple: if the record merely repeats a precise ticket without changing a decision, shorten it. If it reveals a missing user, ambiguous outcome, unsafe data action, untestable success claim, or unbounded scope, it has already paid for itself.
For multi-agent work, complete one shared checkpoint before splitting tasks. Otherwise each agent can optimize a different interpretation. Use the ownership practices in AI Coding Agents: A Team Guide and isolate later writers as described in Git Worktrees for Coding Agents, but do not create worktrees during this first checkpoint because Git is still prohibited.
The decision tree
Use this before invoking an implementation-capable mode:
Start
|
|-- Is the requested behavior already exact, observable, reversible,
| local, and covered by a deterministic check?
| |
| |-- Yes --> Does it touch data, security, money, production,
| | external systems, or multiple owners?
| | |
| | |-- No --> Use a micro-checkpoint:
| | | scope + acceptance + rollback.
| | |
| | |-- Yes --> Use the full checkpoint.
| |
| |-- No --> Use the full checkpoint.
|
|-- Can all ten fields be recorded from supplied evidence?
| |
| |-- No --> Inspect and ask only. Keep implementation locked.
| |
| |-- Yes --> Is evidence internally consistent?
| |
| |-- No --> Stop and resolve the conflict.
| |
| |-- Yes --> Is acceptance repeatable and rollback real?
| |
| |-- No --> Refine the record.
| |
| |-- Yes --> Hand off to implementation.A product’s “plan mode” is not the decision tree. It is one possible enforcement mechanism. Claude Code’s plan mode may run exploratory shell commands, while this workflow bans Git and every write before the record is complete. Codex’s read-only sandbox is useful for inspection, but a workflow still needs explicit fields and a stop condition. Tool permissions enforce capability; the checkpoint defines intent.
For additional containment patterns after the gate, see How to Sandbox AI Coding Agents. For session limits, see Token Budgets and Circuit Breakers for AI Agents and How to Measure Agent Context Overhead.
A 15-minute checkpoint template
Fifteen minutes is a ceiling for a normal, bounded task, not a mandatory delay. Stop early if all fields are clear. For an active incident, use the compressed version shown later.
| Time | Agent action | Output |
|---|---|---|
| 0–2 minutes | Restate the request as a user-visible problem; name the affected user | Problem and affected-user fields |
| 2–5 minutes | Inspect relevant files, supplied logs, screenshots, schemas, and documented commands without writing | Current behavior and evidence with source and confidence |
| 5–7 minutes | Separate desired behavior from the proposed implementation | Desired behavior |
| 7–9 minutes | List hard boundaries and the smallest safe scope | Constraints and non-goals |
| 9–12 minutes | Write a repeatable acceptance test with setup, action, and expected result | Acceptance test |
| 12–14 minutes | Define reversal and containment | Rollback |
| 14–15 minutes | Define pause triggers; decide whether to ask one question or hand off | Stop condition and gate status |
Copy this into an issue comment, task record, or agent prompt:
## No-Code First Checkpoint
- Problem:
- Affected user:
- Observable current behavior:
- Desired behavior:
- Constraints:
- Non-goals:
- Evidence:
- Acceptance test:
- Rollback:
- Stop condition:
Gate status: LOCKED
Missing information:
Confidence:The gate status changes to OPEN FOR IMPLEMENTATION only when every field is present and the evidence does not conflict. Opening the gate authorizes only the implementation scope in the record. It does not authorize deployment, publication, destructive data changes, purchases, external messages, or any other action not explicitly approved.
Use an issue form without making the form the work
Official fact: GitHub says issue forms are YAML definitions in .github/ISSUE_TEMPLATE, can collect structured input, support validations, and convert submitted responses to Markdown in the resulting issue. GitHub also labels issue forms and the form schema as public preview and subject to change. See Syntax for issue forms, GitHub’s form schema, and About issue and pull request templates.
An existing issue form can collect the checkpoint fields, but do not edit repository configuration merely to start one task. After the workflow has proved useful across several tasks, maintainers can separately decide whether to add a form. Required fields improve collection, not truth: a reporter can still enter guesses, so the agent must label evidence and confidence.
For a lightweight form, use text areas for current behavior, desired behavior, evidence, acceptance, rollback, and stop condition; use a dropdown only for a small, stable set such as environment. Avoid requiring technical diagnosis from the affected user. Ask what they observed, not which module they believe is broken.
Write acceptance criteria that can fail
An acceptance criterion is useful only if a reviewer can observe a pass or a fail. Include setup, action, expected result, relevant boundary cases, and the environment when it changes the outcome.
| Weak criterion | Why it is weak | Strong criterion |
|---|---|---|
| “Fix login.” | No user, trigger, or expected result | “Given an active account and a valid password, submitting the login form once redirects to /dashboard; one session is created; the form shows no error.” |
| “Make export faster.” | “Faster” has no baseline or threshold | “For the supplied 100,000-row fixture on the CI runner, export completes in 30 seconds or less in three consecutive runs, and the output row count and checksum match the reference.” |
| “Handle duplicates.” | The matching rule and data outcome are undefined | “In dry-run mode, rows sharing normalized email are reported as one candidate group; no source row is changed; the report includes source IDs and the proposed survivor.” |
| “Improve accessibility.” | The affected interaction is unspecified | “The dialog can be opened, traversed, submitted, and closed with a keyboard; focus enters the dialog on open and returns to the trigger on close; validation errors are identified in text.” |
| “Do not break anything.” | It cannot be exhaustively demonstrated | “The focused regression test passes, the existing package suite passes, and the public response schema remains byte-for-byte identical for the three recorded fixtures.” |
| “Works on mobile.” | No viewport, device behavior, or task | “At 320, 375, and 390 CSS pixels wide, the checkout summary has no horizontal scroll, the total remains visible, and the submit control is fully operable by keyboard and touch.” |
W3C WCAG 2.2 requires labels or instructions where content needs user input, text identification of detected input errors, and error-prevention mechanisms for certain legal, financial, and data-changing submissions. The allowed mechanisms include reversibility, checking with an opportunity to correct, or review and confirmation before finalization. These are accessibility requirements for covered web content, not a universal software checkpoint, but they are useful patterns for high-consequence acceptance tests. See WCAG 2.2, Guideline 3.3.
Do not invent precise performance thresholds. If the product owner has not supplied one and no established service objective exists, record the metric and baseline as evidence, then ask for the target. A fabricated number is not rigor.
Handoff from checkpoint to implementation
The handoff should be smaller than the investigation transcript. It gives the implementation agent a fixed target, allowed surface, tests, and pause triggers.
## Implementation handoff
Checkpoint status: OPEN FOR IMPLEMENTATION
Implement:
- [one observable behavior]
Allowed changes:
- [specific files, package, data copy, or migration artifact]
Do not change:
- [non-goals and protected surfaces]
Evidence to preserve:
- [fixture, log signature, screenshot, query, or reproduction]
Acceptance commands or observations:
1. [setup]
2. [action]
3. [expected result]
Rollback:
- [exact reversal or containment unit]
Stop and report if:
- [scope expands, evidence conflicts, access is missing, destructive action is required,
or a named verification fails for a reason unrelated to the change]
Completion report:
- changed files or records;
- commands and observations with pass/fail results;
- remaining risk and anything not verified.The implementation phase can now use Git if the task and repository rules allow it. Git access is not automatically permission to commit, push, rewrite history, or discard unrelated changes. Likewise, an accepted plan is not permission to deploy. Persistent repository rules still apply, as described in How to Write an AGENTS.md File That Coding Agents Can Follow.
After implementation, compare the diff’s shape with the checkpoint before reviewing line-level quality. How to Review AI-Generated Code explains why a coherent implementation of the wrong interpretation can still pass agent-written tests. For risky workflows, insert a human decision at the boundary using Human-in-the-Loop AI Agents.
Worked example 1: a bug
Scenario: Support reports that a customer can create two invoices by clicking “Create invoice” twice during a slow response. This is a hypothetical example, not a report about a real product.
Completed checkpoint
- Problem: One intended invoice creation can result in two invoice records when the submit action is repeated before the first response returns.
- Affected user: A billing operator using the invoice form on a high-latency connection; the customer receiving the invoice is affected downstream.
- Observable current behavior: In the supplied staging recording, two rapid submissions with the same form values return two identifiers and display two rows. Reproduction has not yet been independently confirmed.
- Desired behavior: One logical submission creates at most one invoice, and the operator receives a clear in-progress state followed by one result.
- Constraints: Preserve the public request and response schema; do not change payment behavior; do not delete existing invoices; do not rely only on a disabled button because requests can be retried outside the browser.
- Non-goals: Redesigning the full billing form, introducing a new job queue, or deduplicating historical invoices.
- Evidence: Support recording, staging request timestamps, and two distinct returned identifiers. Confidence is medium until a controlled staging reproduction succeeds.
- Acceptance test: Given the recorded fixture and the same operation key, send two requests within 100 milliseconds. Exactly one invoice row exists, both responses resolve to the same logical result or one returns the documented in-progress/conflict response, and an unrelated second invoice with a different operation key still succeeds.
- Rollback: Revert the smallest application and schema change as one unit; if a schema addition is required, use a backward-compatible addition that can remain unused while the application change is reverted.
- Stop condition: Stop if the endpoint also triggers payment, if the operation has no stable identity available, if a destructive schema migration is proposed, or if evidence shows the duplicate is created by a downstream service outside the assigned scope.
Gate decision and handoff
The gate remains locked until the staging reproduction or a conflicting explanation is recorded. Once confirmed, the implementation handoff authorizes only idempotent invoice creation and focused tests. It does not authorize a billing rewrite. The first implementation action is to inspect the endpoint and existing persistence constraints with the repository’s approved tools. Verification includes the concurrency test and the existing billing package suite.
Why the checkpoint helped: “disable the button” looked like an obvious fix, but the desired property applies to the operation, not only the interface. The non-goals prevent a queue redesign.
Worked example 2: a small feature
Scenario: Users ask for a “Download CSV” action on a filtered orders table. This is hypothetical.
Completed checkpoint
- Problem: An operations analyst cannot export the currently filtered order results and must copy visible rows manually.
- Affected user: An authenticated operations analyst who filters orders by date and status, then reconciles them in a spreadsheet.
- Observable current behavior: The table supports date and status filters and pagination; no export control is present. The supplied test account has 237 matching rows while the current page shows 25.
- Desired behavior: The analyst downloads one UTF-8 CSV containing all rows that match the active filters, not only the visible page.
- Constraints: Reuse existing authorization and filter semantics; do not expose fields absent from the table’s authorized data model; preserve the current page; cap or stream large exports according to existing service limits.
- Non-goals: Scheduled reports, XLSX output, new filters, column customization, email delivery, and background-job infrastructure.
- Evidence: Product request, screenshot of the filtered table, and the existing list endpoint documentation. Confidence is high about the user flow and medium about maximum result size.
- Acceptance test: Given the fixture with 237 orders, filter to
status=failedand the supplied date range, activate “Download CSV,” and verify one UTF-8 file with the documented header order, 237 data rows, quoted commas and newlines, no unauthorized fields, and values matching the filtered API results. - Rollback: Remove the export control and route while leaving shared CSV utilities untouched only if they have independent tests and callers; otherwise revert the feature as one unit.
- Stop condition: Stop if export requires a new paid service, if authorization differs from the list endpoint, if the maximum dataset cannot be bounded, or if product requires asynchronous delivery.
Gate decision and handoff
The gate opens after the owner answers one question: the maximum supported matching-row count or the existing limit to apply. The implementation scope is the filtered export endpoint, control, and tests. It excludes scheduling and new infrastructure.
Why the checkpoint helped: a small button implied server-side scope, authorization, encoding, pagination, and size behavior. It did not justify a general reporting platform.
Worked example 3: data cleanup
Scenario: A customer export contains duplicate contacts that appear to share an email address. The task is to prepare a safe cleanup, not to mutate production immediately. This is hypothetical.
Completed checkpoint
- Problem: Duplicate contact rows inflate campaign counts and cause repeated outreach.
- Affected user: A campaign operator preparing an audience; contacts may be harmed by repeated messages.
- Observable current behavior: In a timestamped read-only export, 184 rows fall into 79 groups after trimming and case-folding email addresses. Shared email alone does not prove the contacts are the same person.
- Desired behavior: Produce a reviewable candidate report and, only after separate approval, merge records using an agreed survivor rule without losing consent, suppression, ownership, or audit history.
- Constraints: Work from an immutable copy first; preserve source identifiers; treat consent and suppression as safety-critical; no production writes during analysis; no external upload; no deletion without a separately approved execution plan.
- Non-goals: Correcting email addresses, enriching profiles, changing campaign logic, deleting bounced contacts, or merging households solely because they share an address.
- Evidence: Export checksum, export timestamp, schema description, and counts from a read-only analysis. Confidence is high in candidate grouping and low in identity equivalence.
- Acceptance test: A dry run produces a CSV with every candidate group, source IDs, normalized comparison keys, conflict flags, proposed survivor, and proposed field-level result; source data remains byte-identical; every suppression value is preserved with the most restrictive outcome; total source-row accounting reconciles exactly.
- Rollback: The analysis is non-mutating. Any later production action must create a dated backup or reversible mapping from each source ID to the survivor and supply a tested restore procedure before execution.
- Stop condition: Stop on conflicting consent, missing ownership, ambiguous identity, absent backup/restore evidence, candidate counts outside the recorded range, or any request to write production data under the analysis approval.
Gate decision and handoff
The gate opens only for building the local dry-run report from the immutable export. It remains closed for production cleanup. A second checkpoint is required for the mutation, with owner approval, an exact record count, backup verification, batch size, monitoring, and abort threshold.
Why the checkpoint helped: “deduplicate by email” would have converted a similarity signal into an identity decision. Separating candidate detection from mutation makes uncertainty visible and rollback credible.
W3C’s error-prevention patterns are relevant here by analogy: reversible actions, validation with correction, and review before finalization reduce harm in data-changing flows. For broader privacy handling, see How to Redact PII Before Sending Data to an LLM API.
Worked example 4: a time-sensitive incident
Scenario: Five minutes after a release begins, the checkout API’s error rate rises and completed orders fall. This is hypothetical.
An incident still needs all ten fields, but the checkpoint is compressed to three to five minutes. The goal is not a polished design document. It is to prevent an unverified “fix” from destroying evidence or widening impact.
Completed checkpoint
- Problem: Checkout requests are returning more server errors than the recorded pre-release baseline, and order completion is declining.
- Affected user: Customers attempting checkout in the production region shown by monitoring; support and fulfillment teams are affected downstream.
- Observable current behavior: The supplied dashboard shows the error-rate increase beginning within the release window; the top error signature is recorded with timestamp and region. Causation is not yet proven.
- Desired behavior: Restore checkout to the pre-release service objective or the last known stable observed range while preserving order integrity and evidence for follow-up.
- Constraints: Incident commander owns production actions; preserve logs and request identifiers; avoid duplicate charges and orders; no speculative schema change; prioritize a reversible containment action.
- Non-goals: Root-cause refactoring, performance optimization unrelated to the error signature, dependency upgrades, or redesigning checkout during the incident.
- Evidence: Monitoring screenshot, alert timestamp, deployment timeline supplied by the incident commander, top error signature, and regional comparison. Confidence is medium that the release is correlated and low that one changed component is causal.
- Acceptance test: For ten consecutive minutes after containment, the monitored error rate returns to the recorded stable range, synthetic checkout succeeds in the affected region, duplicate-order and payment-integrity checks remain clear, and no new critical error signature appears.
- Rollback: Use the established release rollback runbook under incident-commander approval; do not invent a rollback command in the checkpoint. Record the exact release unit and forward-compatibility warning before execution.
- Stop condition: Stop and escalate if rollback could corrupt in-flight orders, if the previous version is incompatible with the current schema, if the signal spreads to unaffected regions, if payment integrity is uncertain, or if required production approval is absent.
Gate decision and handoff
The gate can open for the already-approved rollback runbook as soon as the incident commander confirms the release unit and compatibility check. It does not open for code changes. After containment, start a separate checkpoint for diagnosis and repair.
Why the checkpoint helped: it separated correlation from causation, named integrity constraints, and made rollback compatibility a stop trigger. Why it must be short: every extra minute may extend user impact. During an incident, the record should be terse and updated as evidence changes.
For instrumenting the post-incident repair, see AI Agent Observability: What to Measure and use deterministic regression checks rather than a narrative claim that the problem is gone.
The anecdotal demand behind the pattern
The following sources are anecdotal demand evidence, not verified product specifications or representative survey data. They were surfaced in a research memo and are used only to explain why practitioners may want a stronger first gate:
- A public post shared a “No Code” declaration as a way to make an agent inspect before implementing: X post. This supports testing the workflow; it does not prove the wording works consistently.
- A public post described overengineering and other recurring coding-agent habits: X post. One report cannot establish a failure rate.
- A public post contrasted agents that make extra changes with agents that stop too often, a task-control problem rather than a simple “more autonomy is better” story: X post.
- A public post reported consuming a paid usage window on a single unsuccessful task: X post. Usage behavior varies by plan, model, task, tool version, and date, so this article makes no numeric plan claim from that post.
The recommendation drawn from these anecdotes is modest: spend a bounded amount of inspection before expensive implementation, make the desired result testable, and stop when uncertainty crosses a named threshold. The checkpoint is not a cure for product limits, and it should not become another source of wasted context.
Failure modes of the checkpoint itself
Planning theater
The agent fills every field with paraphrases of the request, then implements its first idea. Reject records where evidence does not distinguish observation from inference, or where acceptance merely says “tests pass.”
Overengineering the gate
A two-line change receives architecture diagrams, a migration strategy, and fifteen hypothetical edge cases. Apply the friction test. Exact, local, reversible tasks can use scope, acceptance, and rollback only.
Solution-first requirements
“Add Redis” is recorded as the problem. Rewrite it as the observed user or system behavior. Redis may be a candidate implementation later, but the checkpoint should remain valid if a simpler solution wins.
Questions without inspection
The agent asks the user for facts already present in the repository or supplied evidence. Inspection comes first when it is read-only and in scope. Ask only for decisions, missing observations, or ownership facts the agent cannot derive safely.
Evidence destruction
The agent runs a formatter, test with write-on-start behavior, cleanup script, dependency installer, or configuration generator during “investigation.” Treat any command with uncertain side effects as disallowed until the gate opens. Reading source is not permission to execute it.
Permanent planning mode
The record is complete, but the agent keeps refining language instead of handing off. The 15-minute ceiling and explicit gate status prevent this. If a decision remains, ask one focused question or activate the stop condition.
Acceptance criteria written by the same mistaken model
An agent can encode its misunderstanding into both implementation and tests. Have the affected user or task owner review the observable desired behavior before implementation when the risk is material. A separate reviewer should compare the final diff with the checkpoint. See Human Review Coverage for AI Workflows for risk-based review placement.
Frequently asked questions
1. Is this just planning mode with a new name?
No. Plan or read-only modes are enforcement tools. The checkpoint is a content contract: ten recorded fields, a strict no-write/no-install/no-config/no-Git boundary, and an explicit handoff. You can use it with Claude Code, Codex, another agent, or a human developer.
2. Why ban all Git, including git status?
The first checkpoint does not need Git to identify the user problem and acceptance test. A blanket ban is easy to audit and avoids differences in aliases, hooks, helpers, filters, and subcommands. If history is essential, record that need and authorize a narrow Git inspection after the gate opens.
3. Can the agent run tests during the checkpoint?
Only when the team has already classified the exact test command as read-only and the checkpoint policy explicitly allows it. The safer default is no execution because tests can create snapshots, caches, databases, containers, or generated files. Supplied test output can still be inspected.
4. Where should the checkpoint record live?
Use the existing task surface: issue, ticket, agent transcript, or reviewable run output. Do not create a new repository file for every task unless the team has intentionally adopted that process.
5. What if a required field is unknown?
Write Unknown, the consequence of not knowing, and the cheapest safe way to learn it. Keep the gate locked if the unknown changes scope, safety, user outcome, acceptance, or rollback. A harmless unknown can become a documented implementation assumption.
6. Who opens the gate?
For a low-risk, precisely bounded task, the agent can open it when the team’s policy allows autonomous implementation. A human owner should open it for production, security, privacy, payment, destructive data, external side effects, or material scope decisions.
7. Does a complete checkpoint guarantee a correct implementation?
No. It reduces ambiguity and makes review more objective. It cannot guarantee correct diagnosis, complete evidence, sound design, defect-free code, or safe deployment.
8. How is a non-goal different from a constraint?
A constraint limits how the accepted outcome may be achieved, such as preserving an API or avoiding production writes. A non-goal names adjacent outcomes the task will not pursue, such as redesigning the whole form.
9. How detailed should rollback be?
Detailed enough to identify the reversal unit and prove recovery is possible. “Revert if needed” is weak. Name the files, feature switch, backup, mapping, compatible release, or manual recovery path, plus any condition that makes reversal unsafe.
10. What if rollback is impossible?
The stop condition should block implementation until risk is accepted by the appropriate owner or the design becomes reversible. For inherently irreversible work, use a simulation, dry run, copy, limited cohort, or review-and-confirm step first.
11. How do we keep the checkpoint from consuming the usage window?
Cap it at 15 minutes for normal tasks, keep the template stable, inspect only the likely surface, and ask at most the questions that change a decision. If no field changes after another round of exploration, stop and report the unresolved item.
12. Should the checkpoint be added to AGENTS.md?
Add only the persistent rule and location of the template if the team adopts it broadly. Keep individual task records out of AGENTS.md. That file should remain a repository operating guide, not a backlog.
13. Can GitHub issue forms enforce the process?
They can require structured inputs, but they cannot verify that evidence is true or that the acceptance test is meaningful. They also cannot by themselves prevent an agent from editing. Combine the form with read-only permissions and review.
14. How does this work for non-code data tasks?
Replace “implementation” with “transformation.” Inspection and profiling use an immutable copy; acceptance reconciles counts and invariants; rollback maps outputs to inputs; production mutation requires a separate authorization boundary.
15. When should we remove the checkpoint?
Remove or shorten it when repeated use shows no decision benefit for a task class and deterministic safeguards already make mistakes cheap and reversible. Keep evidence from a small trial rather than treating process as permanent by default.
Sources
Official primary sources and anecdotal demand evidence checked on 2026-07-24.
Official primary sources
- Anthropic, Choose a permission mode: current Plan mode behavior, mode switching, and approval flow.
- Anthropic, Common workflows: repository exploration, bug workflow, testing, and planning before editing.
- Anthropic, Claude Code CLI reference: non-interactive invocation and permission-mode flags.
- Anthropic, Security: permission architecture, working-directory boundaries, sandboxing, and user responsibility.
- Anthropic, Best practices for Claude Code: current official prompting and codebase-work guidance.
- OpenAI, Codex CLI: official terminal capabilities for inspection, editing, commands, and repeatable work.
- OpenAI, Prompting: current official guidance for writing prompts for Codex and other ChatGPT surfaces.
- OpenAI, Agent approvals and security: read-only planning, sandbox boundaries, approval policies, and permission combinations.
- OpenAI, Non-interactive mode:
codex execbehavior, default read-only sandbox, machine-readable output, and explicit write permissions. - OpenAI, Custom instructions with AGENTS.md: repository guidance discovery and scoped instruction files.
- GitHub, Syntax for issue forms: YAML location, top-level keys, fields, and validations.
- GitHub, Syntax for GitHub’s form schema: form elements, identifiers, attributes, and constraints.
- GitHub, About issue and pull request templates: structured issue input and template locations.
- ISO, ISO/IEC/IEEE 29148:2018: public abstract and lifecycle status for requirements engineering.
- ISO, ISO 9241-210:2019: public abstract for human-centred design of interactive systems.
- ISO, ISO 9241-11:2018: public abstract for usability definitions and concepts.
- ISO, ISO/IEC 25010:2023: public product quality model and listed requirements, testing, and acceptance uses.
- ISO, ISO/TR 25060:2023: public framework for usability-related information items.
- NIST, Requirements Verification Tools: public list of useful requirement qualities.
- NIST, Common Industry Specification for Usability Requirements: context of use, performance and satisfaction criteria, and evaluation context.
- NIST, Human Centered Design: users, tasks, environments, requirements, design, and evaluation activities.
- W3C, Web Content Accessibility Guidelines 2.2: input assistance and error-prevention success criteria.
- IETF, RFC 2119: official meanings and cautions for normative requirement keywords.