Why “AI-First” ≠ “Auto-Pilot”

AI-first means you optimize your development loop around intelligent assistants, not that you abandon engineering judgment. The value comes from repeatable agent tasks—spec writing, boilerplate, refactors, tests, and routine integration—while humans own system design, risk calls, and final review.

If you tried “prompt the model and pray,” you probably saw flaky outputs and context blow-ups. The fix is structure:

• Clear tasks with inputs/outputs.
• Tooling for file access, repos, APIs, and sandboxes.
• Policies (what “good” looks like) and evidence (tests, logs, diffs).
• Tight feedback loops: short runs, rapid critique, re-runs.

Bottom line: Treat agents like a junior team you manage. Give precise briefs, expose good tools, and require proof before merge.

---

The Misconception (and Why It Hurts Teams)

“Auto-pilot” implies you can toss vague prompts at a model and get production-ready code. That’s how you get drift, regressions, and mystery-meat PRs. AI-first keeps humans in the loop and constrains tasks so agents excel at the repeatable parts while you keep control of architecture, security, and risk.

Anti-patterns to avoid

• Prompt-and-pray: giant context dumps, no tools, no tests.
• Mega-runs: 8 hours of agent drift → massive, unreviewable PR.
• Secret leakage: pasting credentials into prompts or logs.
• Tool sprawl: too many tools with fuzzy contracts.

Replace them with

• Small, testable scopes (30–90 minutes of work per loop).
• Strong interfaces (MCP tools), not model guesswork.
• Evidence gates (tests + diffs + smoke logs in every PR).
• Opinionated rules (what to change, and what not to touch).

---

The AI-First Development Loop (At a Glance)

Short, instrumented cycles beat long, speculative runs.

---

1) How to Write a Great Brief (with Examples)

Good brief (copy/paste & edit):

# Task: Stripe Webhook Ingestion
**Goal:** Verify Stripe signatures, store events, ensure idempotency, and expose metrics.

**Constraints:** Node 20, TypeScript, hexagonal architecture, Postgres.

**Acceptance:**
- Endpoint `POST /webhooks/stripe`
- Verify HMAC via `Stripe-Signature`
- Table `webhook_events(event_id UNIQUE, type, payload, received_at)`
- Exponential backoff for transient failures
- Vitest unit tests for HMAC + idempotency
- README: setup, env vars, run commands
- Mermaid sequence diagram for flow

**Evidence to include in PR:**
- `npm run lint` output
- `npm run test` results (summary)
- 30s smoke log (`npm run smoke` or k6)
- `git diff --stat` + list of changed files

Bad brief:

“Integrate Stripe.”

Why this matters: Agents are excellent at bounded work with clear inputs/outputs. Vague goals = vague code.

---

2) Tooling: Give the Agent Real Levers (MCP Ideas)

Expose tools via MCP (or your agent runner) so the model reads/writes files, runs linters/tests, and hits mocked APIs instead of hallucinating.

• mcp-fs: read/write only src/, tests/, migrations/
• mcp-git: create feature branch, show diffs, conventional commits
• mcp-run: run npm run lint, npm run test, npm run smoke
• mcp-apis: test-mode clients (e.g., Stripe) with sample payloads
• mcp-knowledge: coding standards, runbooks, API contracts
• mcp-evals: ESLint, Vitest/Jest, k6 smoke wrappers

Tip: Start with the minimum set of tools that make correct work possible. Add more only when you can measure a cycle-time or quality win.

---

3) Policy + Evidence: Ship with Proof

Define a Definition of Done and demand evidence in every PR.

# .clinerules (excerpt)
project:
  name: service-registry
  language: typescript
  node_version: "20.x"

definition_of_done:
  - Endpoint: POST /webhooks/stripe with signature verification
  - DB: migration creates webhook_events (unique: event_id)
  - Tests: unit tests for HMAC + idempotency (Vitest/Jest)
  - Docs: README updates + sequence diagram (Mermaid)
  - Evidence: paste linter output, test results, and a 30s smoke log

guardrails:
  - No unrelated module changes
  - Keep commits small; meaningful messages
  - Use env-based config; never print secrets
  - Follow hexagonal architecture boundaries

commands:
  lint: "npm run lint"
  test: "npm run test"
  smoke: "npm run smoke"

PR evidence template (drop into .github/pull_request_template.md):

## Summary
- What changed and why

## Evidence
- Lint:

$ npm run lint ✔ 0 problems, 0 warnings

- Tests:

$ npm run test Test Files 6 passed (6) Assertions 37 passed

- Smoke (k6 or curl):

Requests 50 Errors 0 p(95) 120ms

## Docs
- [ ] README updated
- [ ] Sequence diagram added/updated

---

4) Tight Feedback Loops: 30–90 Minute Slices

Each loop ends with a reviewable PR and attached evidence. If it’s too big to review quickly, split the task.

Deciding slice size

---

End-to-End Mini Example (Stripe Webhooks)

1) Minimal route (Express)

// src/routes/stripeWebhook.ts
import express from "express";
import type { Request, Response } from "express";
import { verifyStripeSignature, handleEvent } from "../services/stripeWebhook";

export const router = express.Router();

router.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req: Request, res: Response) => {
  try {
    const sig = req.headers["stripe-signature"];
    if (!sig || typeof sig !== "string") return res.status(400).send("Missing signature");

    const event = verifyStripeSignature(req.body, sig); // throws on mismatch
    await handleEvent(event); // idempotent insert + business logic
    return res.status(200).send("ok");
  } catch (err: any) {
    if (err.name === "SignatureVerificationError") return res.status(400).send("Bad signature");
    console.error("webhook error:", err);
    return res.status(500).send("internal");
  }
});

2) Idempotent handler

// src/services/stripeWebhook.ts
import crypto from "crypto";
import { db } from "../db"; // your pg client
import { STRIPE_WEBHOOK_SECRET } from "../config";

export function verifyStripeSignature(rawBody: Buffer, signature: string) {
  const expected = crypto.createHmac("sha256", STRIPE_WEBHOOK_SECRET).update(rawBody).digest("hex");
  const provided = signature.split(",").find(s => s.startsWith("v1="))?.slice(3);
  if (!provided || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
    const e: any = new Error("SignatureVerificationError"); e.name = "SignatureVerificationError"; throw e;
  }
  return JSON.parse(rawBody.toString("utf8"));
}

export async function handleEvent(event: any) {
  const id = event.id;
  const type = event.type;

  // Idempotency via unique constraint on event_id
  const result = await db.query(
    "INSERT INTO webhook_events(event_id, type, payload, received_at) VALUES ($1,$2,$3, NOW()) ON CONFLICT (event_id) DO NOTHING RETURNING event_id",
    [id, type, event]
  );
  if (result.rowCount === 0) return; // duplicate; already processed

  // TODO: perform business actions based on 'type'
}

3) Migration (Postgres)

-- migrations/20250827_create_webhook_events.sql
CREATE TABLE IF NOT EXISTS webhook_events (
  event_id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  payload JSONB NOT NULL,
  received_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

4) Unit tests (Vitest)

// tests/stripeWebhook.test.ts
import { describe, it, expect } from "vitest";
import { verifyStripeSignature } from "../src/services/stripeWebhook";

describe("verifyStripeSignature", () => {
  it("throws on bad signature", () => {
    const body = Buffer.from(JSON.stringify({ ok: true }));
    expect(() => verifyStripeSignature(body, "v1=deadbeef")).toThrow();
  });
});

5) Smoke (k6)

// smoke/stripe.js
import http from "k6/http";
import { check, sleep } from "k6";

export default function () {
  const payload = JSON.stringify({ id: "evt_test_1", type: "ping" });
  const res = http.post("http://localhost:3000/webhooks/stripe", payload, {
    headers: { "Content-Type": "application/json", "stripe-signature": "v1=fake" }
  });
  check(res, { "status is 400 or 200": r => r.status === 400 || r.status === 200 });
  sleep(0.2);
}

What you got: a runnable path from route → handler → migration → unit tests → smoke script, with idempotency and signature checks.

---

“Refactor with Proof” Playbook (Safe Agent Refactors)

Brief: “Refactor UserService to dependency-inject the email client; add unit test stubs and keep public methods stable.”

Evidence: Before/after diff, passing tests, and a small k6 smoke (or curl) against one endpoint.

Checklist:

• Public API unchanged (compile + unit tests prove it).
• Internal coupling reduced (constructor injection).
• Lint passes; cyclomatic complexity reduced in hot functions.
• README updated if usage changes.

---

Documentation-as-a-Deliverable (Don’t Skip This)

Ask the agent to update docs as part of the task. Require:

• “What changed and why” section in PR.
• Setup/Run instructions kept current.
• Mermaid diagrams for flows and components.

Example (Mermaid sequence):

---

Security & Compliance Notes (Practical, Not Scary)

• Secrets: pull from env or a secret manager; never paste into prompts or logs.
• Auditability: require PR evidence blocks + CI artifacts; keep a short retention policy for logs containing traces.
• SOC 2 mindset: encrypt sensitive data in transit and at rest, document key management, and record exceptions with risk rationale.
• PII minimization: redact or hash where possible; never dump entire payloads in logs by default.

These aren’t just checkboxes—they reduce real-world blast radius.

---

GitHub Actions: Minimal CI That Mirrors Agent Checks

# .github/workflows/ci.yml
name: ci
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm test -- --run
      - name: Smoke (optional)
        run: |
          npm run start &
          SERVER_PID=$!
          sleep 2
          npx k6 run smoke/stripe.js || true
          kill $SERVER_PID

Keep CI aligned with the agent’s local checks. “Green locally, green in CI.”

---

Metrics That Matter (How You Know It’s Working)

Track whether AI-first is actually helping; put these on a lightweight dashboard:

• Lead Time (idea → merged PR)
• Change Failure Rate (% of PRs causing hotfix/rollback)
• MTTR (time to recover from failure)
• Golden Path Coverage (% of critical flows with tests/smokes)

If agents don’t move at least one metric, tighten scope, improve tooling, or clarify briefs.

---

One-Day Adoption Plan

Morning

• Write the brief and .clinerules.
• Enable minimal MCP tools (fs, git, run).
• Give the agent read-only first; validate it proposes a plan.

Afternoon

• Ship a tiny feature with tests + README.
• Require evidence in the PR; run CI; merge if green.

Evening

• Retro: What was noisy? Tighten rules, shrink scopes.
• Pick tomorrow’s next 60–90 minute slice.

---

FAQ

Q: Which model should I use?
A: Use what your org approves. Strong reasoning + code models are great; the process (briefs, tools, evidence) matters more than the logo.

Q: Will agents replace engineers?
A: No—agents accelerate repeatable work. Humans still own product sense, system design, trade-offs, and accountability.

Q: How do I stop agents from touching unrelated code?
A: Guardrails: scoped fs access; explicit module boundaries; PR diffs must only include files listed in the plan.

Q: How do I handle secrets in test/smoke?
A: Use env vars and fake/test tokens; never hardcode real secrets; redact logs.

---

Glossary (Speed Round)

• MCP (Model Context Protocol): A way to expose tools (fs, git, run, evals) to models in a controlled, auditable manner.
• Evidence: Lint, test, smoke logs, and diffs attached to PRs proving the change works.
• Golden Path: The core user flows you can’t afford to break—automate tests/smokes here first.
• Idempotency: Safe to retry without duplicating side effects (e.g., unique constraint on event_id).

---

Copy-Paste Starter Checklist

• Write a 1-page brief with constraints + acceptance + evidence
• Enable minimal MCP tools (fs, git, run, evals)
• Add .clinerules and a PR evidence template
• Enforce small scope (≤90 min) + short feedback loops
• Track lead time + failure rate + MTTR + golden path coverage

---

AI-first ≠ auto-pilot. It’s a disciplined, auditable workflow where agents handle the repeatable work and engineers make the important calls. Clear tasks, real tools, explicit policies, hard evidence, and short feedback loops—that’s the recipe.