yanacuti1121/yana-ai/ai-first-engineering

When to Use

• Use when: AI generates >30% of new code on the team
• Use when: recurring bugs in the same files/areas despite fixes
• Use when: agents misunderstand requirements repeatedly
• Use when: code review process wasn't designed for generated code

Core Shift

In AI-first teams:

• Planning quality matters more than typing speed
• Test coverage matters more than implementation speed
• Explicit contracts matter more than implicit conventions
• Acceptance criteria matter more than story points

Architecture for AI Agents

Design code so agents can navigate it reliably:

✓ Explicit module boundaries — clear import paths, no implicit globals
✓ Typed interfaces at every boundary — agents follow types, not conventions
✓ Stable contracts — rename carefully; agents break on renamed functions
✓ Small files — agents context-window out on 500+ line files
✓ One responsibility per file — agents over-generalize in catch-all files
✗ Barrel index.ts with 50 re-exports — agents import wrong things
✗ Implicit side effects on import — agents can't reason about order
✗ Magic strings/numbers — agents copy the wrong value

Requirements for Agent Handoff

Before handing a task to an agent:

1. One clear deliverable — "Add X to Y" not "improve the auth flow"
2. Acceptance criteria as test cases — "passes these 3 tests" beats "works correctly"
3. Explicit constraints — "touch only these files", "do not change the public API"
4. Failure definition — "if you can't do X without touching Y, stop and report"

Code Review for AI Output

AI-generated code review focuses on behavior, not style:

• [ ] Does it handle the edge cases a human would remember?
• [ ] Are security assumptions correct (auth checks, input validation)?
• [ ] Does it regress any existing behavior?
• [ ] Are error states handled (not just happy path)?
• [ ] Did it touch files outside declared scope? (scope drift)

Style, formatting, naming — let the linter handle it. Don't waste review on what tools enforce.

Regression Strategy

When AI fixes a bug, immediately write a regression test:

Bug found in X → Write failing test for X → Apply fix → Test passes → Commit both

Never trust "AI reviewed its own work" — same model carries same blind spots into both steps.

Anti-Fake-Pass

❌ Calling requirements "clear" when they have no acceptance criteria
❌ Reviewing AI output for style instead of behavior
❌ No regression test after an AI-introduced bug is fixed
❌ Architecture with implicit conventions AI can't read from types
✅ Every requirement answered: "how do I know this is done?"
✅ Regression test committed alongside every AI bug fix