AI Coding Workflow

The deliverable is not “the model wrote code.” It is a change an engineer can explain, test, revert, and hand to a reviewer. Tools change; the stable workflow is to define the outcome, understand the repository, implement in small steps, verify, and preserve evidence.

---

A reliable development loop

outcome and boundaries
  → read repository rules
  → locate current behaviour and neighbouring patterns
  → plan with acceptance criteria
  → capture the failing baseline
  → implement the smallest vertical slice
  → unit / integration / UI or real-client verification
  → review diff and security boundaries
  → scoped commit plus evidence

---

Choose a surface by task shape

Do not treat a product brand as a permanent capability boundary:

Cursor, Claude Code, Codex, and Kiro may cover several surfaces. Capabilities and prices change, so a learning page should not permanently crown one product as the best.

---

Write a Task Brief before prompting

## Outcome

After a failed login, the user sees a recoverable error instead of a blank page.

## In scope

-   Login form error state
-   User messages for 401 and 429
-   Unit tests and browser regression

## Out of scope

-   Changing the authentication provider
-   Changing public URLs
-   Redesigning the whole page

## Constraints

-   Preserve the API contract
-   Reuse the repository request/error helper
-   Never log passwords or tokens

## Acceptance

-   Wrong password shows a clear message
-   429 asks the user to retry later
-   The form works again after refresh
-   Tests and the browser flow pass

“Fix login” makes the agent guess the outcome, scope, and finish line. A brief is not a long PRD; it records the decisions that must not be guessed.

---

Explore before editing

pwd
rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g 'README.md'
rg -n "login|signIn|401|429" src
git status --short
git log -5 --oneline

Ask the agent to report the current data path, nearest existing pattern, user changes that must be preserved, the narrowest reproduction, and whether the task touches URLs, access, data, or publication.

Starting without evidence often creates duplicate utilities, changes the wrong directory, or overwrites parallel work.

---

A plan should expose risk

1. Preserve 401/429 categories in the request error mapper
2. Render recoverable copy from the login form
3. Add mapper boundary tests
4. Run wrong-password and rate-limit browser flows
5. Stage only the scoped files

Every step needs a completion signal. A plan that changes a public URL, deletes data, sends a message, or deploys production requires explicit authority before execution.

---

Implement and verify in small increments

change one behaviour
  → run the narrowest test
  → inspect the diff
  → repair or continue
  → complete the vertical slice
  → run the higher-level check

A command exiting zero is not always the requested user outcome. Verification must reach the actual finish line.

---

Review the diff, not the agent summary

Check scope drift, invented imports, deviation from existing patterns, hidden writes or network calls, error semantics, server-side access boundaries, and whether tests validate behaviour rather than mirror implementation.

git diff --check
git diff --stat
git diff -- path/to/scoped/files
git status --short

The summary can omit a file. Git is the change source of truth.

---

Put team knowledge in the right artefact

Kiro Specs currently organise features into requirements, design, and tasks; coding tools also support project rule files. The durable principle is versioned, scoped guidance instead of repeating conventions in every chat.

---

Measure productivity with evidence

Use comparable time windows and task groups. If the baseline is missing, record unavailable rather than inventing a number.

---

Additional gates for high-risk work

• Auth, access, and billing: the human writes the threat model and invariants first.
• Migration: backup, dry run, sample, and rollback; never let an agent execute production by assumption.
• Concurrency: validate multiple processes or pods, not only one process.
• Deletion and publication: resolve exact targets, approve, and read back external state.
• Secrets: keep them out of logs, prompts, screenshots, and commits.

AI can diagnose and propose a patch; the accountable engineer must understand the failure modes.

Practice task

Choose one real, small bug:

1. Write the brief and out-of-scope list.
2. Ask for read-only exploration with cited repository patterns.
3. Save the failing baseline.
4. Implement one behaviour at a time with the narrowest test.
5. Review the diff and execute the actual user flow.
6. Produce an evidence pack: files, commands, results, uncovered risk, and commit.

Definition of done

• Outcome, scope, and acceptance were not guessed by the agent.
• The same flow has before and after evidence.
• I read the scoped diff and can explain high-risk code.
• The commit excludes other workspace changes.
• Productivity claims use comparable evidence, not invented figures.

Related reading

• Vibe Coding in Practice
• AI Rules Configuration
• Claude Code Context Management
• Long-Running Agent Harness

Official references

• https://code.claude.com/docs/en/quickstart
• https://kiro.dev/docs/specs/
• https://kiro.dev/docs/steering/