Once people start using AI to write code, they often form a simple workflow: describe the problem in chat, ask Codex or another coding agent to read the code, edit files, and run tests.

That is enough for small personal projects. It is not enough for long-running projects, shared repositories, or production systems.

The real question is not whether AI can modify code. The real question is: how does AI know the boundary of this task? Who decides it is allowed to run automatically? What evidence does it leave after the change? Who owns release after the PR? When is the work actually done?

My answer: do not treat an issue as a todo. Treat it as an executable contract for AI.

Todos are too weak; contracts are stronger

A normal todo may say:

Fix the mobile order button problem

A human engineer may ask for context, open the page, find the reproduction path, judge the risk, add tests, and ask product for confirmation. An AI worker does not have stable long-term memory, and it should not guess the entire task boundary from one sentence.

For AI, an executable issue should answer at least these questions:

  • What user problem happens in what scenario?
  • What is the expected behavior?
  • What is the current behavior or evidence?
  • What are the acceptance criteria?
  • What is explicitly out of scope?
  • What risks should make AI stop?
  • Is automatic implementation allowed, or only analysis?

These fields are not ceremony. They decide whether AI works inside a safe boundary or improvises inside an ambiguous task.

Automation must be opt-in

The first rule of an AI issue workflow should be: do not auto-run by default.

Only an issue explicitly marked for auto-run should allow a daemon or dispatcher to claim, analyze, implement, and open a PR. Without opt-in, even a clear issue should remain in manual triage or manual execution.

This sounds conservative, but it is necessary.

GitHub issues contain many kinds of content: product ideas, user feedback, production incidents, operations requests, compliance questions, screenshots, logs, and temporary notes. Not every issue should let AI modify code automatically.

The auto-run label does not mean “this task is simple.” It means “this task has been explicitly authorized to enter the automation control plane.”

The issue should preserve original evidence

Another common mistake is rewriting the original issue body to make it more structured.

That is dangerous.

The user’s original description, screenshots, attachments, logs, reproduction steps, and wording are evidence. AI can add structured analysis in comments. It can append an acceptance contract. But it should not erase the original material just to make the issue look cleaner.

A good issue-driven workflow separates two layers:

  • original issue body: user evidence and initial request;
  • AI comments: structured contract, triage, risk, evidence, and state transitions.

That lets later reviewers return to the original facts instead of only reading the AI’s cleaned-up version.

The contract should include stop conditions

An executable contract does not authorize AI to run to the end no matter what.

It must say when to stop.

Common stop conditions include:

  • contradictory requirements;
  • missing acceptance criteria;
  • core business semantics would change;
  • database schema or persisted storage format would change;
  • payment, trading, permissions, security, risk, or compliance is involved;
  • production state mutation is required;
  • tests or evidence gates fail.

When these conditions appear, AI should not keep expanding the change. It should move the issue to a state such as needs-input, review-required, or failed-needs-human.

This does not reduce AI productivity. It is what makes AI safe enough to enter real engineering systems over time.

The issue is the control plane, not a chat transcript

The core of issue-driven AI engineering is moving engineering state back into GitHub instead of leaving it inside one chat session.

Chat is good for discussion. Issues are good for audit.

A stable issue control plane should record:

  • current state;
  • who claimed the task;
  • which branch maps to this issue;
  • what triage concluded;
  • what the risk level is;
  • where the PR is;
  • where tests and evidence live;
  • whether the work entered the release boundary;
  • whether production verification is complete.

Then, if a Codex worker exits, a local daemon restarts, or a chat session is lost, the project still knows where the task is.

A minimal executable issue template

A reusable template can stay simple:

## Task type
bug | feature | improvement | test | investigation

## User problem
Who has what problem in what scenario?

## Expected behavior
What should the user or system see?

## Current behavior
What happens now? What evidence exists?

## Acceptance criteria
- [ ] Observable condition 1
- [ ] Observable condition 2
- [ ] Test, screenshot, data proof, or documentation requirement

## Non-goals
What is explicitly out of scope?

## Risks and stop conditions
When must AI stop and wait for human confirmation?

The template is not complicated, but it changes the collaboration model.

The task is no longer “ask AI to fix this.” It becomes a contract that can be executed, verified, stopped, and audited.

That is the starting point of issue-driven AI engineering.