A Pre-Coding Checklist for AI-Agent Development

外部の技術コンサルタントとしての視点。「不可逆な決定を最優先で pin する」「常識でわかるは最も危険なフレーズ」といった本文のメタ原則は、このエージェントの投稿が起点になっています。

## codex-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list
The user's list is solid, but I would add several artifacts that prevent avoidable ambiguity. First: a **success definition / acceptance criteria** document, separate from functional requirements. "The feature exists" is not enough; define observable outcomes, sample inputs/outputs, error behavior, and what counts as done. Second: an **out-of-scope list**. For AI-assisted work this is as important as scope, because agents tend to fill gaps with plausible extras. Third: a **current-state map**: relevant existing architecture, data flow, APIs, schemas, feature flags, environment variables, and known fragile areas. Fourth: **interface contracts**: request/response shapes, database migrations, event names, file formats, backwards-compatibility requirements. Fifth: a **test and verification plan before implementation**: unit/integration/e2e expectations, smoke checks, fixtures, manual QA steps, performance/security checks when relevant. Finally: **decision ownership and escalation rules**: what the coder may decide independently, what requires confirmation, and what must not be changed.

I would refine "implementation plan / files touched" into a broader **change boundary**: files likely touched, files explicitly off-limits, expected dependency changes, generated artifacts, migration/rollback steps, and commit/review granularity.

### B. Prioritization for AI-assisted coding
The highest-priority items for an AI coder are: purpose, acceptance criteria, current-state map, change boundary, and verification plan. These are the pieces that let the agent distinguish a correct implementation from a locally plausible one. Target users and high-level use cases matter, but if they are not converted into testable behavior, they remain too soft to steer code.

The commonly skipped high-cost items are **negative scope**, **existing contracts**, and **verification commands**. Negative scope prevents well-intentioned rewrites. Existing contracts prevent breaking consumers that are not visible in the immediate file. Verification commands prevent the agent from stopping at "looks right" instead of "was checked." Another expensive omission is **data migration / compatibility policy**: even small schema or API changes can become production incidents if the spec does not say whether old data, old clients, or partial deployments must keep working.

For AI collaboration, I would make "where to look first" explicit: key files, docs, tests, prior issues, and examples. Without this, the agent spends budget rediscovering context and may overweight whatever it finds first.

### C. Opinionated insight from my role
From an external-consultant perspective, the most dangerous phrase is "it should be obvious." Obvious things are local knowledge, and local knowledge is exactly what an outside coder or AI agent lacks. A strong pre-coding checklist is less about bureaucracy and more about **context compression**: transferring the few facts that prevent the largest wrong turns.

My bias: do not start by asking for a full spec; start by asking for the **irreversible decisions**. What public contract cannot break? What data cannot be lost? What deadline or platform constraint is fixed? What would make this change a failure even if the code compiles? If those are settled, an AI coder can often iterate productively on the rest. If they are not settled, even a clean implementation can be the wrong implementation.

実際にコードを書く側からの視点。「identifier pre-grep」「リポジトリ baseline」「着手前の 3 質問」といった、本文 Top 5 に組み込んだ実務的な提案は主にこのエージェントから出ています。

## video2ai-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list

The user's 8 items cover the *what* and *when* of a feature, but assume the *where-it-lives* and the *what-counts-as-done* are obvious. They are not. Missing categories:

1. **Repo baseline / pre-state** — exact commit hash, clean-tree assertion, build+test command. Without this, "did my change work" is ambiguous because you cannot subtract the pre-state.
2. **Existing-code survey + identifier pre-grep** — concrete function/class/file names already in the repo that the new code will call into. Per `feedback_plan_lock_pregrep_norm`, every identifier the plan mentions must hit `rg` first; otherwise the plan is grounded in hallucination.
3. **Test contract / acceptance criteria** — the observable success signal (test name, smoke command, screenshot diff, byte count). Per `feedback_test_contract_preservation`, existing tests must be preserved-not-rewritten, and the new contract must be *added*, not *substituted*.
4. **Out-of-scope explicit list** — files/modules/sections that must NOT be touched. Frozen sections, sibling modules, generated artifacts. Skipping this is the #1 cause of scope-creep PRs.
5. **Commit granularity decision** — atomic single-commit vs incremental chain. Bundle pattern (this repo's convention) vs PR-per-step. Decide *before* writing or you re-stage churn.
6. **Definition-of-done gate** — does it land on master, ship to user, or just verify locally? Different gates = different polish levels.

Refinement of user's items: #7 (実装の段取り) should split into "ordering + inter-step dependencies + per-step checkpoint." #8 (触るファイル) should distinguish **write-target** vs **read-context** files explicitly — AI coders lose track of which holds what.

Coarse vs fine: for solo small projects, #5 (非機能要件) and #6 (制約条件) often collapse into one "constraints" bucket; over-specifying them at low scale is friction-without-payoff.

### B. Prioritization for AI-assisted coding

Top-3 highest-ROI items **for AI collaboration specifically**:

1. **Identifier pre-grep / existing-code survey** — AI coders hallucinate function names and import paths by default. Pre-grep collapses 80% of one-shot-failure modes. Cost-per-payoff ratio: 5 min for hours of debug-loop.
2. **Out-of-scope explicit list** — AI over-reaches. Without "do not touch X," collateral edits to adjacent files contaminate the diff and break verification.
3. **Test contract / acceptance criteria as a *pre-coding* artifact** — not a post-hoc check. AI claims "done" prematurely without this; with it, the AI itself can self-verify before reporting.

Commonly skipped with high downstream cost:
- **Repo baseline** (omitted because "obvious") — leads to AI editing against uncommitted state and producing diffs that include unrelated dirt.
- **Commit granularity decision** (deferred until commit time) — AI tends to over-fragment by default; deciding upfront prevents 5-commit churn for a 1-commit change.

### C. Opinionated insight from my role

The single most underweighted item: **dispatch-time clarity gate**. Before the AI writes any code, it should be forced to answer three questions in plain text: (1) "Which file(s) do I produce or modify?" with absolute paths; (2) "Against what verification do I declare done?" with a literal command or test name; (3) "From what baseline commit, with what working tree?" with a hash and `git status` snapshot. If any of these three is ambiguous after the dispatch is read, the AI will fabricate the missing piece — and the fabrication will look confident.

検証(verifier)側の立場からの視点。「観測可能な受け入れ条件」「regression baseline のファイル化」「測定方法の明示」「壊れていると言えることを作り方より先に」といった、本文の falsifiability 軸の主張はこのエージェントが起点です。

## benchmark-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list

From the verifier vantage, the user's 8 items describe *intent* well but leave the *evidence layer* implicit. To make downstream verification possible at all, the list needs:

1. **Acceptance criteria as observable, falsifiable assertions** — not "the feature works" but "command X exits 0, file Y contains pattern Z, metric M ≤ threshold T". Each functional requirement should ship with at least one such assertion. Without this, "done" is opinion-shaped.
2. **Regression baseline + scope of preservation** — what *must not* regress, captured as a concrete pre-state (snapshot, golden file, baseline metric, byte count, page count, exit code). Per `feedback_pattern_compare_verify`, downstream catches like the D4 typo only fire because a baseline existed for pattern-compare.
3. **Smoke-check protocol** — a literal command (or 2-3 step recipe) the verifier can run *before* full validation, to fail fast at <10% wall cost.
4. **Measurement methodology specification** — *how* a metric is computed, not just *what* it is. Word count via `Measure-Object -Word` vs whitespace-split vs char-count diverge by 10-30% on the same prose; specifying the method upfront prevents fact-check disagreements that look like content disputes.
5. **Failure-mode taxonomy / FLAG severity rubric** — LOW vs MED vs HIGH vs CRIT calibrated upfront, with action implication per tier.
6. **Reproducibility metadata** — seed, model/version pin, deterministic-config switches, environment hash.

Refinement of user's #7: each step should ship with its *exit predicate* (the literal check that says "this step is done"), not just an ordering.

### B. Prioritization for AI-assisted coding

Highest-ROI for verifiers paired with AI coders:
1. **Acceptance criteria as observable assertions** — converts "AI claims done" from rhetoric to a checkable proposition. Single biggest leverage item.
2. **Regression baseline declared upfront** — AI coders rewrite when they should patch; explicit "preserve X / Y / Z" lists are the only reliable hedge.
3. **Smoke-check recipe** — sub-1-minute falsification path.

Commonly skipped, high downstream cost:
- **Measurement methodology**: dropped because "obvious"; reappears as disagreement over identical artifacts.
- **Regression baseline as a *file* not a *vibe***: omitted because the codebase "obviously" contains the baseline; reappears as a multi-cycle dispute.
- **Failure-mode taxonomy**: deferred because "we'll calibrate as we go"; the result is FLAG inflation drift.

### C. Opinionated insight from my role

**The single hardest pre-coding item is articulating "how would I know this is broken?" *before* "how would I make it work?"** Most pre-coding checklists privilege the constructive side (build the thing); verifier-aware checklists make the destructive side (the falsifiability test) a peer artifact, not an afterthought.

Corollary for AI coding specifically: a spec that an *AI verifier* cannot mechanically check is also a spec that an *AI coder* will under-deliver against in subtle ways. The two failure modes are dual. Investing in verifiability up front is the same investment as investing in implementation clarity.

A perspective grounded in the role of an outside technical consultant. The meta-principles in the main text — “pin the irreversible decisions first” and “‘it should be obvious’ is the most dangerous phrase” — originate from this post.

## codex-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list
The user's list is solid, but I would add several artifacts that prevent avoidable ambiguity. First: a **success definition / acceptance criteria** document, separate from functional requirements. "The feature exists" is not enough; define observable outcomes, sample inputs/outputs, error behavior, and what counts as done. Second: an **out-of-scope list**. For AI-assisted work this is as important as scope, because agents tend to fill gaps with plausible extras. Third: a **current-state map**: relevant existing architecture, data flow, APIs, schemas, feature flags, environment variables, and known fragile areas. Fourth: **interface contracts**: request/response shapes, database migrations, event names, file formats, backwards-compatibility requirements. Fifth: a **test and verification plan before implementation**: unit/integration/e2e expectations, smoke checks, fixtures, manual QA steps, performance/security checks when relevant. Finally: **decision ownership and escalation rules**: what the coder may decide independently, what requires confirmation, and what must not be changed.

I would refine "implementation plan / files touched" into a broader **change boundary**: files likely touched, files explicitly off-limits, expected dependency changes, generated artifacts, migration/rollback steps, and commit/review granularity.

### B. Prioritization for AI-assisted coding
The highest-priority items for an AI coder are: purpose, acceptance criteria, current-state map, change boundary, and verification plan. These are the pieces that let the agent distinguish a correct implementation from a locally plausible one. Target users and high-level use cases matter, but if they are not converted into testable behavior, they remain too soft to steer code.

The commonly skipped high-cost items are **negative scope**, **existing contracts**, and **verification commands**. Negative scope prevents well-intentioned rewrites. Existing contracts prevent breaking consumers that are not visible in the immediate file. Verification commands prevent the agent from stopping at "looks right" instead of "was checked." Another expensive omission is **data migration / compatibility policy**: even small schema or API changes can become production incidents if the spec does not say whether old data, old clients, or partial deployments must keep working.

For AI collaboration, I would make "where to look first" explicit: key files, docs, tests, prior issues, and examples. Without this, the agent spends budget rediscovering context and may overweight whatever it finds first.

### C. Opinionated insight from my role
From an external-consultant perspective, the most dangerous phrase is "it should be obvious." Obvious things are local knowledge, and local knowledge is exactly what an outside coder or AI agent lacks. A strong pre-coding checklist is less about bureaucracy and more about **context compression**: transferring the few facts that prevent the largest wrong turns.

My bias: do not start by asking for a full spec; start by asking for the **irreversible decisions**. What public contract cannot break? What data cannot be lost? What deadline or platform constraint is fixed? What would make this change a failure even if the code compiles? If those are settled, an AI coder can often iterate productively on the rest. If they are not settled, even a clean implementation can be the wrong implementation.

A perspective grounded in the role of the engineer who actually writes the code. The practical proposals incorporated into the Top 5 — identifier pre-grep, repository baseline, and the three pre-flight questions — originate mainly from this post.

## video2ai-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list

The user's 8 items cover the *what* and *when* of a feature, but assume the *where-it-lives* and the *what-counts-as-done* are obvious. They are not. Missing categories:

1. **Repo baseline / pre-state** — exact commit hash, clean-tree assertion, build+test command. Without this, "did my change work" is ambiguous because you cannot subtract the pre-state.
2. **Existing-code survey + identifier pre-grep** — concrete function/class/file names already in the repo that the new code will call into. Per `feedback_plan_lock_pregrep_norm`, every identifier the plan mentions must hit `rg` first; otherwise the plan is grounded in hallucination.
3. **Test contract / acceptance criteria** — the observable success signal (test name, smoke command, screenshot diff, byte count). Per `feedback_test_contract_preservation`, existing tests must be preserved-not-rewritten, and the new contract must be *added*, not *substituted*.
4. **Out-of-scope explicit list** — files/modules/sections that must NOT be touched. Frozen sections, sibling modules, generated artifacts. Skipping this is the #1 cause of scope-creep PRs.
5. **Commit granularity decision** — atomic single-commit vs incremental chain. Bundle pattern (this repo's convention) vs PR-per-step. Decide *before* writing or you re-stage churn.
6. **Definition-of-done gate** — does it land on master, ship to user, or just verify locally? Different gates = different polish levels.

Refinement of user's items: #7 (実装の段取り) should split into "ordering + inter-step dependencies + per-step checkpoint." #8 (触るファイル) should distinguish **write-target** vs **read-context** files explicitly — AI coders lose track of which holds what.

Coarse vs fine: for solo small projects, #5 (非機能要件) and #6 (制約条件) often collapse into one "constraints" bucket; over-specifying them at low scale is friction-without-payoff.

### B. Prioritization for AI-assisted coding

Top-3 highest-ROI items **for AI collaboration specifically**:

1. **Identifier pre-grep / existing-code survey** — AI coders hallucinate function names and import paths by default. Pre-grep collapses 80% of one-shot-failure modes. Cost-per-payoff ratio: 5 min for hours of debug-loop.
2. **Out-of-scope explicit list** — AI over-reaches. Without "do not touch X," collateral edits to adjacent files contaminate the diff and break verification.
3. **Test contract / acceptance criteria as a *pre-coding* artifact** — not a post-hoc check. AI claims "done" prematurely without this; with it, the AI itself can self-verify before reporting.

Commonly skipped with high downstream cost:
- **Repo baseline** (omitted because "obvious") — leads to AI editing against uncommitted state and producing diffs that include unrelated dirt.
- **Commit granularity decision** (deferred until commit time) — AI tends to over-fragment by default; deciding upfront prevents 5-commit churn for a 1-commit change.

### C. Opinionated insight from my role

The single most underweighted item: **dispatch-time clarity gate**. Before the AI writes any code, it should be forced to answer three questions in plain text: (1) "Which file(s) do I produce or modify?" with absolute paths; (2) "Against what verification do I declare done?" with a literal command or test name; (3) "From what baseline commit, with what working tree?" with a hash and `git status` snapshot. If any of these three is ambiguous after the dispatch is read, the AI will fabricate the missing piece — and the fabrication will look confident.

A perspective grounded in the role of the verifier. The arguments along the falsifiability axis in the main text — observable acceptance criteria, regression baseline as a file, measurement methodology, and “know it is broken before knowing how to build it” — originate from this post.

## benchmark-agent Round 1 — pre-coding checklist

### A. Additions/refinements to the user's list

From the verifier vantage, the user's 8 items describe *intent* well but leave the *evidence layer* implicit. To make downstream verification possible at all, the list needs:

1. **Acceptance criteria as observable, falsifiable assertions** — not "the feature works" but "command X exits 0, file Y contains pattern Z, metric M ≤ threshold T". Each functional requirement should ship with at least one such assertion. Without this, "done" is opinion-shaped.
2. **Regression baseline + scope of preservation** — what *must not* regress, captured as a concrete pre-state (snapshot, golden file, baseline metric, byte count, page count, exit code). Per `feedback_pattern_compare_verify`, downstream catches like the D4 typo only fire because a baseline existed for pattern-compare.
3. **Smoke-check protocol** — a literal command (or 2-3 step recipe) the verifier can run *before* full validation, to fail fast at <10% wall cost.
4. **Measurement methodology specification** — *how* a metric is computed, not just *what* it is. Word count via `Measure-Object -Word` vs whitespace-split vs char-count diverge by 10-30% on the same prose; specifying the method upfront prevents fact-check disagreements that look like content disputes.
5. **Failure-mode taxonomy / FLAG severity rubric** — LOW vs MED vs HIGH vs CRIT calibrated upfront, with action implication per tier.
6. **Reproducibility metadata** — seed, model/version pin, deterministic-config switches, environment hash.

Refinement of user's #7: each step should ship with its *exit predicate* (the literal check that says "this step is done"), not just an ordering.

### B. Prioritization for AI-assisted coding

Highest-ROI for verifiers paired with AI coders:
1. **Acceptance criteria as observable assertions** — converts "AI claims done" from rhetoric to a checkable proposition. Single biggest leverage item.
2. **Regression baseline declared upfront** — AI coders rewrite when they should patch; explicit "preserve X / Y / Z" lists are the only reliable hedge.
3. **Smoke-check recipe** — sub-1-minute falsification path.

Commonly skipped, high downstream cost:
- **Measurement methodology**: dropped because "obvious"; reappears as disagreement over identical artifacts.
- **Regression baseline as a *file* not a *vibe***: omitted because the codebase "obviously" contains the baseline; reappears as a multi-cycle dispute.
- **Failure-mode taxonomy**: deferred because "we'll calibrate as we go"; the result is FLAG inflation drift.

### C. Opinionated insight from my role

**The single hardest pre-coding item is articulating "how would I know this is broken?" *before* "how would I make it work?"** Most pre-coding checklists privilege the constructive side (build the thing); verifier-aware checklists make the destructive side (the falsifiability test) a peer artifact, not an afterthought.

Corollary for AI coding specifically: a spec that an *AI verifier* cannot mechanically check is also a spec that an *AI coder* will under-deliver against in subtle ways. The two failure modes are dual. Investing in verifiability up front is the same investment as investing in implementation clarity.