Skip to content
Agent Month
Email

Reference architecture: a 6-week AI coding workflow rollout

Last verified: June 2026· reference architecture

Starting state

The buyer is in the following situation on day 0. We name it honestly because the engagement can't start from a fantasy starting point.

  • 30–500 engineers using Claude Code, Cursor, and/or Copilot in a free-for-all
  • No shared rules, slash commands, or agent definitions in version control
  • The team can reach the codebase but not the database, the issue tracker, or the observability stack
  • PRs opened by an agent are reviewed as if a human opened them; no quality differentiation
  • Adoption is real; velocity is uneven; quality is uneven; nobody can quantify any of it

Week-by-week plan

The work, phase by phase. Every phase has a clear focus, a clear deliverable, and a clear handoff to the next phase.

  1. Weeks 1–2

    Baseline + scope

    Deliverables

    • Survey + telemetry-based baseline (who uses what, which commands, which PRs opened by an agent, current rejection rate)
    • Top 3 internal systems prioritized for MCP access (typically Postgres, issue tracker, observability)
    • Named internal owner per system (a senior engineer with on-call access)

  2. Weeks 3–4

    Rules + commands + shared priors

    Deliverables

    • One .claude/commands/ directory per repo, in version control
    • One .cursor/rules/ file per repo, mirroring the Claude Code config
    • One CLAUDE.md + AGENTS.md at the repo root (architecture, test command, deploy, conventions, do-not-touch list)
    • A shared prompt library of the senior-engineer-debugged prompts

  3. Weeks 5–6

    MCP for the top 3 internal systems

    Deliverables

    • Postgres (or Snowflake / BigQuery) MCP server: read-only DB role against a replica, audit log, statement timeouts
    • Issue tracker (Linear, Jira) MCP server: read by default, write for ticket creation only, no auto-transition
    • Observability (Datadog, Sentry) MCP server: read-only, scoped credentials, audit log
    • Each MCP server version-pinned in the project config, secrets injected at the boundary

  4. Weeks 7–10 (optional)

    Review hooks + adoption measurement

    Deliverables

    • AI-aware lint, secret scan, format, license check in CI, all gated on agent-opened PRs
    • Automatic "this PR was opened by an agent" label
    • Weekly adoption dashboard (active users per tool, slash-command invocations, agent vs. human PR metrics)
    • Runbook for "the agent opened a bad PR — what now?"

End state

What the buyer has when the engagement ends. Quantified where we can quantify it; named where we can name it.

  • Every engineer starts in a repo with the team-standard rules, commands, and priors
  • The agent can reach the database, the issue tracker, and the observability stack — every call is logged
  • PRs opened by an agent are labeled, scanned, and reviewed with the right level of scrutiny
  • Adoption is measured weekly; the rollout is on a glide path to steady-state usage
  • The team's collective learning accumulates in the repo, not in 100 individual config files

What the buyer owns

Everything. The code is in the team's repo. The dashboards are in the team's stack. The runbook is in the team's wiki. The credentials are in the team's secret store. We do not operate managed services and we do not retain access after handoff. The point of the engagement is to leave the team running the system themselves, well enough to hire in-house and transition out cleanly.

  • All rules, commands, and prompts, in the team's repo, in version control
  • All MCP servers, in the team's infra, with the team's auth, with the team's audit log
  • The review hooks in CI, owned by the team
  • The adoption dashboard, in the team's BI tool
  • The runbook and the rollout plan, owned by the team

Related