AI-Assisted Delivery: Best Practice Guide

Core thesis: AI generates code rapidly; speed without automated verification is pure risk. The formula for success: Clear intent (spec) + small steps + automated proof (tests, architectural rules, CI) + human judgment.

1. Core Principles

1. Intent > Code. Humans define the "what" and "why"; AI produces the "how". Intent must be written and versioned (spec).
2. Small Batches. Both speed and mistakes scale with AI. Small deltas mean easy review and straightforward rollbacks.
3. Verification Must Be Automated. "Eyeball and approve" does not scale. Test suites, linters, architecture fitness tests, and mutation tests serve as the ultimate referees for AI.
4. Human Accountability. The engineer who commits and approves a PR owns the code as if written by hand.
5. The Capable but Fallible Intern Model. Fast, knowledgeable, confident, and occasionally wrong. Never leave the model without guardrails.
6. Context is an Engineering Discipline. Output fidelity is directly proportional to context quality and relevance.
7. Measure and Improve. Rely on objective engineering metrics (DORA, change failure rate, rework rate) rather than gut feel.

2. Repository Preparation: AI-Ready Repository

2.1 Instruction Files (AGENTS.md / CLAUDE.md)

• Maintain a single source of truth at the repository root: AGENTS.md (cross-tool standard), referenced by tool-specific files like CLAUDE.md if needed.
• Essential contents:
  • A 5-sentence architectural summary and primary purpose
  • Build, test, lint, and run commands (copy-pasteable and deterministic)
  • Directory structure and boundary rules
  • Coding style, naming conventions, and error-handling patterns
  • Explicit "Do Not" guidelines (e.g., no direct push to main, no manual schema migration edits, never commit secrets)
  • Definition of Done
• Keep it concise (ideally < 200 lines). Link to dedicated documentation files for deep dives.
• In monorepos, place localized AGENTS.md files in relevant subdirectories (e.g., /services/payments/AGENTS.md).
• Review and version instruction files like code. Whenever an agent repeats a mistake twice, convert that lesson into a permanent rule.

2.2 Documentation Structure

/docs
  /adr            -> Architecture Decision Records (why was this decided?)
  /specs          -> Feature specifications
  /architecture   -> C4 diagrams, dependency boundaries
  /runbooks       -> Operational guides
  /glossary.md    -> Domain glossary (ubiquitous language)

• ADRs are invaluable for AI: they allow agents to understand previous decisions without reopening closed architectural debates.
• A domain glossary guarantees naming consistency across data models, APIs, and business rules.

2.3 Fast Feedback Infrastructure

• Provide single-command verification: make check, npm run verify, or ./gradlew check (formatter + linter + type-checker + unit tests + architecture tests).
• Keep unit test suites fast (< 1–2 minutes). Agents tend to bypass slow test runs.
• Eliminate test flakiness completely. Flaky tests poison AI iteration loops.

3. Spec-Driven Development (SDD)

3.1 Why Specs Matter

"Vibe coding" works for throwaway prototypes, not production engineering. A formal spec exposes ambiguity before any code is generated and gives the agent a verifiable target.

3.2 Framework and Tooling Options

3.3 Anatomy of a High-Quality Spec

1. Problem and Objective (user value, quantifiable success metrics)
2. Non-Goals — explicit boundaries preventing agent scope creep
3. User Scenarios (Given / When / Then)
4. Acceptance Criteria (verifiable, measurable, testable)
5. Constraints (performance thresholds, security guarantees, backward compatibility)
6. Open Questions (mandate that the agent asks questions rather than assuming)
7. Data Contracts and API Schemas (OpenAPI, JSON Schema, Protobuf)
8. Edge Cases and Failure Modes

3.4 The SDD Workflow

Constitution (project core rules)
   │
   ▼
Specify (define "what")
   │
   ▼
Clarify (resolve ambiguities, agent asks questions)
   │
   ▼
Plan (technical architecture, ADRs)
   │
   ▼
Tasks (small, decoupled, ordered backlog)
   │
   ▼
Implement (task-by-task execution with TDD)
   │
   ▼
Verify (validate against spec acceptance criteria)

3.5 Governance Rules

• Human reviews and approves the spec before code generation begins. This represents the single highest-leverage intervention point.
• When code and spec conflict, update the spec first.
• Scope individual tasks to take at most a few hours, targeting single PRs.
• Map every acceptance criterion in the spec to at least one automated test for complete traceability.
• Keep specs inside the repository as living documentation that stays updated across feature lifecycles.

4. Agent Capabilities: Skills, Subagents, Hooks, and MCP

4.1 Skills

• Definition: Self-contained folders (SKILL.md) loaded dynamically by agents containing instructions, scripts, and domain resources.
• Purpose: Package repetitive, team-specific workflows: "add new endpoint", "write migration", "generate release notes", "apply PR review checklist".
• Best Practices:
  • Enforce single responsibility per skill; provide clear descriptions specifying exact activation triggers.
  • Turn repetitive tasks into skills rather than retyping long prompts.
  • Delegate deterministic work to scripts rather than LLM token generation.
  • Version skills in-repo (.claude/skills/), review them, and share across teams.

4.2 Slash Commands and Prompt Templates

• Standardize routine tasks: /spec, /plan, /review, /fix-ci, /commit.
• Enforce structured, predictable input and output formats.

4.3 Subagents (Specialized Collaborators)

• Run specialized roles in isolated context windows: code-reviewer, test-writer, security-auditor, researcher, doc-writer.
• Benefits: Prevents primary context contamination and ensures an independent second opinion (the author agent never acts as its own reviewer).
• Golden Rule: The implementer and reviewer must operate in separate contexts or through different agents.

4.4 Hooks (Deterministic Guardrails)

• Enforce rules that models might forget via programmatic hooks:
  • PreToolUse: Block destructive commands (e.g., rm -rf, git push --force, production DB access)
  • PostToolUse: Automatically trigger formatting, linting, and targeted test suites on file change
  • Stop: Ensure make check passes before marking any task as complete
  • Secret scanning and deny-listing for sensitive files (.env, raw migrations)
• Core Principle: Prompts express intent; hooks enforce invariant rules.

4.5 Model Context Protocol (MCP) and Tool Integrations

• Connect issue trackers, CI pipelines, observability platforms, read-only databases, and design systems via MCP.
• Principle of Least Privilege: Read-only by default; write permissions must be explicitly granted and audited.
• Never mount untrusted MCP servers; inspect tool descriptions to mitigate prompt injection and tool poisoning risks.

4.6 Permissions and Sandboxing

• Employ allowlist-based permission models: permit safe read commands, require human confirmation for file modifications and network calls.
• Run agents inside isolated development environments (containers, devcontainers, Git worktrees). Never expose production credentials.
• "Yolo mode" or permission skipping is strictly reserved for ephemeral, throwaway sandboxes.

5. The Core Loop: Explore → Plan → Implement → Verify

1. Explore: The agent reads existing code without writing new files, identifying current architecture conventions and patterns.
2. Plan: Step-by-step implementation plan generated in plan mode; a human reviews and approves the plan. An invalid plan guarantees invalid code.
3. Implement: Small, incremental steps accompanied by tests at each stage.
4. Verify: Automated tests, architecture fitness rules, static analysis, smoke tests, and acceptance criteria validation.
5. Reflect: Convert mistakes into updated AGENTS.md instructions, skills, or hook rules. Invariant rules belong in the system, not in human memory.

Practical Tactics

• One Task, One Session: Clear context (/clear) or launch a new session once a task finishes.
• Prevent context rot by proactively summarizing or rotating sessions when windows fill up.
• If an agent fails to solve an issue within 2–3 turns, stop: refine the problem statement or adjust the architectural approach.
• Use Git worktrees for concurrent agent execution: each agent operates in an isolated working tree on its own branch.
• Perform cross-model verification on mission-critical paths using two distinct LLM families.

6. Granular Commits and Delivery Discipline

6.1 Commit Standards

• Atomic Commits: Single logical change; must compile and pass all tests independently.
• Commit frequently after every verifiable task step to establish clean recovery checkpoints.
• Adopt Conventional Commits (feat:, fix:, refactor:, test:, docs:) to enable automated changelogs and semantic versioning.
• Separate refactoring, functional behavioral changes, and formatting into distinct commits.
• Write descriptive commit messages explaining the "why", stripping verbose AI boilerplate.
• Tag AI contributions transparently using trailers such as Co-authored-by: Agent <agent@local>.

6.2 Pull Request Guidelines

• Target fewer than 400 lines of diff per PR with a singular focus. Massive AI dumps cannot be effectively reviewed.
• Slice larger initiatives using stacked PRs.
• PR descriptions must include: spec references, summary of changes, test evidence, identified risks, and details of where AI was applied.
• Utilize Draft PRs early for architecture visibility.

6.3 Branching and Release Strategy

• Trunk-Based Development with short-lived feature branches (< 1–2 days).
• Decouple deployment from release using feature flags, supporting canary deployments and gradual rollouts.
• Ensure every change is reversible: support clean rollbacks and backward-compatible schema changes (expand/contract pattern).
• Enforce strict branch protection: merges require green CI pipelines.

7. Testing Strategy: The True Referees of AI

7.1 Test-Driven Development (TDD)

• Red → Green → Refactor: Write the failing test first, followed by minimal implementation.
• Humans write or approve the test; AI generates the implementation. Allowing an agent to write its own test risks tailoring the assertions to faulty logic.
• Instruct agents explicitly never to delete or skip tests to make builds green; monitor for test modification via hooks.
• Derive automated acceptance tests directly from Given/When/Then scenarios.

7.2 The Testing Pyramid

7.3 Architecture Fitness Tests

Transform architecture diagrams into executable fitness functions. AI naturally tends to erode architecture by copying nearby code without respecting module boundaries.

• Tooling: ArchUnit (Java/Kotlin), NetArchTest (.NET), dependency-cruiser / eslint-plugin-boundaries (JS/TS), import-linter (Python), go-arch-lint (Go).
• Sample Invariant Rules:
  • The domain layer must have zero dependencies on infrastructure
  • Controllers cannot bypass application services to invoke repositories directly
  • Cyclic dependencies between packages are forbidden
  • Package boundaries in modular monoliths must be strictly preserved
  • Prohibit deprecated APIs, print statements, or unapproved libraries
• Run architecture tests inside make check and CI as mandatory gates.
• Provide clear assertion error messages so agents can parse failures and auto-remediate.

7.4 Mutation Testing

Code coverage only measures what code was executed; mutation testing measures what defects were caught. AI-generated tests frequently achieve high coverage while asserting very little.

• Tooling: PIT/Pitest (JVM), Stryker (JS/TS/.NET), mutmut (Python), cargo-mutants (Rust), go-mutesting (Go).
• Practices:
  • Run mutation testing incrementally on changed code (diff mutation) on pull requests; reserve full runs for nightly builds.
  • Set target thresholds: aim for mutation scores > 70–80% on critical domain packages.
  • Treat surviving mutants as defective test suites. Dispatch targeted tasks to agents: "Write assertions that kill these surviving mutants."
  • Filter out boilerplate (DTOs, configurations, getters) to avoid mutation noise.

8. Static Quality and Security Gates

8.1 Local Pre-Commit / Pre-Push Gates

• Deterministic formatters (Prettier, Spotless, Ruff, gofmt)
• Strict linters (ESLint, Ruff, Checkstyle, golangci-lint)
• Type checking under strict flags (tsc --strict, mypy --strict)
• Secret detection (gitleaks, trufflehog)
• Conventional commit message linting (commitlint)

8.2 CI Pipeline Gates

1. Reproducible build and locked dependency installation
2. Format, lint, and type validation
3. Unit, integration, and contract test suites
4. Architecture fitness tests
5. Incremental mutation testing
6. SAST (CodeQL, Semgrep, SonarQube)
7. SCA / Dependency Vulnerability Scanning (Dependabot, Snyk, OSV-Scanner)
8. Secret scanning, container scanning, and IaC inspection (Trivy, Checkov)
9. SBOM generation, cryptographic signing (Sigstore/cosign), SLSA provenance
10. Quality Gate enforcement (duplication, cyclomatic complexity thresholds)
11. Staged deployment: Staging → Smoke → Canary → Production

8.3 AI-Specific Security Threats

• Hallucinated Dependencies (Package Slopsquatting): Verify that every package suggested by an agent genuinely exists, is maintained, and is safe. Require explicit human approval for new package introductions.
• Indirect Prompt Injection: Untrusted content in issues, PR comments, or scraped documentation can hijack agent behavior. Never grant write or network execution authority to agents ingesting untrusted input.
• Secret Leakage: Prevent secrets and customer PII from leaking into LLM context windows or logs via rigorous deny-lists.
• Outdated or Insecure Patterns: Training data often contains deprecated cryptographic patterns or known CVEs. Mandatory SAST and security-focused review are essential.
• Expert Review for Critical Modules: Authentication, authorization, cryptography, billing, and PII handling require mandatory human specialist sign-off.

9. Code Review in the AI Era

• AI acts as the first-pass reviewer; humans serve as final decision-makers. Leverage automated bots (CodeRabbit, Copilot review) for mechanical sanity checks.
• Human review must prioritize architectural fit, spec compliance, security posture, domain correctness, and test assertion validity. Leave syntax and formatting to automated linters.
• Targeted Review Questions for AI Code:
  • Does this introduce accidental complexity or over-engineering?
  • Has the agent reinvented existing internal utility libraries?
  • Is error handling robust, or does it silently catch and ignore failures?
  • Do the tests genuinely assert behavior, or do they only inflate coverage?
  • Did the agent smuggle in unexpected dependencies or configuration changes?
• "Never merge code you do not understand." If the submitter cannot explain the logic, reject the PR immediately.

10. Context Engineering

• Supply the right context at the right moment: Avoid dumping entire codebases. Provide relevant files, ADRs, specs, and representative code examples.
• Adopt progressive disclosure: Load skills and sub-instructions only when invoked.
• Use Concrete Examples: Pointing to an existing production module as a reference yields significantly better results than abstract explanations.
• Treat context windows as scarce budgets: Large logs, irrelevant files, and stale conversational history degrade generation quality.
• Maintain external state across extended sessions (PLAN.md, PROGRESS.md, structured task checklists).
• Use exact file paths and symbol names instead of ambiguous references.

11. Prompting and Task Definitions

Objective:        <Why this is needed, measurable user value>
Context:          <Spec links, relevant files, applicable ADRs>
Scope:            <Specific, bounded implementation tasks>
Non-Goals:        <Explicitly excluded items>
Acceptance:       <Testable criteria and edge cases>
Constraints:      <Performance SLOs, security rules, zero new dependencies>
Verification:     <Exact commands to execute: make check>
Expected Output:  <Target commits, PR summary, ask questions before coding>

• Provide positive and negative examples.
• Require the agent to present an implementation plan before modifying files.
• Equip the agent with clear self-verification mechanisms; an agent capable of verifying its own work delivers 2–3x higher quality.

12. Refactoring Legacy Code

• Pin existing behavior using characterization and approval tests before authorizing AI refactoring.
• Execute large-scale mechanical migrations (framework upgrades, language transitions) using deterministic codemods (OpenRewrite, jscodeshift); use AI solely for edge cases.
• Apply the Strangler Fig pattern: carve out small vertical slices, backed by tests and architecture rules at every increment.
• Refactoring commits must never alter observable behavior; existing test suites must pass unchanged.

13. Observability and Operations

• AI-generated services must produce first-class telemetry: structured JSON logging, Prometheus metrics, and OpenTelemetry distributed tracing.
• SLO and alert definitions form an integral part of the Definition of Done.
• Maintain operational runbooks in agent-readable formats to accelerate incident investigation.
• Feed postmortem learnings back into AGENTS.md, skills, or architecture fitness rules.

14. Engineering LLM-Powered Products

• Eval-Driven Development: Measure prompt and model changes against automated evaluation suites (golden datasets, LLM-as-judge benchmarks, human sampling).
• Version prompts as code and execute regression evals inside CI.
• Implement runtime guardrails: input/output schema validation, PII masking, and adversarial red teaming.
• Track inference token budgets, latency distributions, and cost per request alongside model fallback chains.

15. Engineering Culture and Governance

• Clear AI Usage Policy: Document approved tools, classification tiers for source code, IP guidelines, and vendor privacy policies.
• Individual Accountability: "The AI wrote it" is never an acceptable defense. The approving engineer is accountable for production stability.
• Continuous Skill Growth: Ensure early-career engineers develop core architectural skills rather than blindly delegating comprehension to AI.
• Community Knowledge Sharing: Maintain an internal registry of effective skills, prompts, and hooks; hold weekly sessions on what worked and what failed.
• Beware Automation Bias: Green test suites do not automatically prove correctness. Maintain healthy skepticism.

16. Engineering Metrics

Warning: Raw lines of code and "percentage of code generated by AI" are vanity metrics. If velocity accelerates while Change Failure Rate rises, your verification safety net has failed.

17. Anti-Patterns to Avoid

18. Phased Adoption Roadmap

Phase 0 (Week 1): Foundations

• Write a concise AGENTS.md (commands, architecture boundaries, forbidden patterns, DoD)
• Provide a single-command local check: make check
• Configure pre-commit hooks (formatting, linting, secret detection)
• Enable branch protection and required CI status checks
• Publish organizational AI policy

Phase 1 (Weeks 2–4): The Safety Net

• Stabilize test suites and quarantine flaky tests
• Implement the first 5–10 Architecture Fitness Tests
• Integrate SAST, SCA, and secret scanning into CI
• Adopt PR templates, the < 400 lines limit, and Conventional Commits
• Establish the /docs/adr directory and record initial decisions

Phase 2 (Months 1–2): Process Engineering

• Pilot Spec-Driven Development (SDD) via Spec Kit, OpenSpec, or structured markdown templates
• Establish test-first cultural standards and TDD workflows
• Introduce incremental mutation testing on PRs with nightly full runs
• Build custom team skills, slash commands, and safety hooks
• Deploy dedicated reviewer subagents

Phase 3 (Months 2–3): Maturity and Scaling

• Standardize feature flagging and canary release infrastructure
• Expand contract testing and property-based testing
• Make runbooks and telemetry schemas machine-readable for agents
• Deploy engineering metric dashboards (DORA + AI rework metrics)
• Adopt parallel Git worktree workflows for multi-agent development

19. One-Page Operational Checklist

• Before Every Task: Spec and acceptance criteria defined? · Plan approved by a human? · Relevant context provided? · Verification command specified?
• Before Every Commit: Atomic and granular? · Tests passing locally? · Architecture rules verified? · Linters, formatters, and secret scans clean?
• Before Every PR: Diff < 400 lines? · Spec linked? · Test evidence attached? · New dependencies vetted? · Surviving mutants killed? · Can I explain every line of this code?
• At Sprint Close: Have repeated errors been encoded into AGENTS.md, skills, or architecture tests? · Have rework and quality metrics been reviewed?

The essence of AI-assisted delivery: Grant the agent speed, but encircle that speed with automated verification. Specs define direction, small commits preserve rhythm, architecture and mutation tests guarantee correctness, hooks and sandboxes enforce security, and human review provides final judgment. Keep invariant rules out of human heads and embedded inside the system.

Related publications