../writing

Keep an AI Agent Grounded While It Builds a Feature

Naseebullah Ahmadi  Senior Software Engineer, London

An AI agent produces plausible, well-formatted code that quietly drifts from what was asked. The fix is a loop with a durable spec: a real GitHub issue the agent must reference, and a two-axis review (standards vs. spec) that runs against it before the PR opens.

#ai
#workflow
#github
#claude-code
#gh-cli
3 min read
#engineering #ai
In one line

File a real GitHub issue as the spec, and reference its number in a commit. Before you open the PR, run a two-axis review: does the diff follow the repo's standards, and does it do what the issue asked.

You're here when

Signs this is your situation
  • You're about to have an agent build a feature and want it not to drift
  • The agent keeps producing clean code that solved a slightly different problem
  • You want the agent to check its own work before you review it by hand
  • You have the code-review / testing-strategy skills installed and want a loop around them

The play

  1. 1File the issue first: gh issue create. Write it like someone else has to implement it from just that text; this is the spec everything downstream points back to.
  2. 2Branch from master, named after the issue.
  3. 3Build, loading domain skills (accessibility, testing conventions) at the point they're relevant, not all at once up front.
  4. 4Commit with the issue number in at least one message, #128. Load-bearing: the review step finds the spec here.
  5. 5Before the PR, run the review skill: it diffs HEAD against a base, resolves the issue from the commit log, and reports standards and spec as two separate results.
  6. 6Fix what it flags, then push, open the PR, and reference the issue again (Closes #128) so merging closes the loop.
@itsnas loop.sh
codeloop.sh
gh issue create --title "Add tags filter popover" --body "…"
git switch -c 128-tags-filter-popover
 
# …build, committing as you go…
git commit -m "Add tags filter popover (#128)"
 
# self-review before the PR: resolves #128 from the commits,
# reports standards and spec separately
# /code-review master
 
git push -u origin HEAD
gh pr create --body "Closes #128"
main
Nas (@itsnas)

Which path

The issue is real and specific

  • The review's spec axis has something to check: you get "does it do what was asked" for free.
  • Both axes run; fix what either one flags.

No issue, or it's vague / after-the-fact

  • Stop and write the issue properly first: a retrofitted issue gives the review nothing meaningful to check against.
  • If you truly can't, run standards only. Don't block on an axis you can't feed.

Gotchas

  1. 1

    Skipping the issue reference in commits

    The review step then has nothing to fetch: it can check style but not whether you built the right thing. The whole loop is downstream of (#128) in a commit message.

  2. 2

    Merging the two review axes into one

    A clean, idiomatic diff can feel done even when it solved the wrong problem. Keep standards and spec separate so the loud signal doesn't drown out the quiet one.

  3. 3

    A bad or empty base ref

    Validate the ref resolves and the diff is non-empty before doing anything expensive with it: fail fast, not two steps in.

  4. 4

    Loading every skill up front

    Skills are context. Load the domain ones when the work reaches them, or the agent spends its budget re-reading rules it isn't using yet.

Confirm you're clear

  1. 1git log on the branch has at least one #123-style reference.
  2. 2The review ran both axes and you've addressed what it flagged.
  3. 3The PR body closes the issue, so the merge closes the loop.