AI-Assisted Infrastructure for Your Team

~~A few months into this project, a colleague asked me how the homelab was going~~ (Not true, I did this in a week and folks didn’t know I had started working on my homelab again). I gave the honest answer: faster than I expected, with more documentation than I’d ever produced on a side project, but not because AI was writing everything, because the process forced everything to be written down. He asked what I meant. I described the session structure: bounded scope, one PR per session, knowledge captured at the end. He was quiet for a moment, then said: “How would we do that on the team?”

That question is harder than it sounds. The methodology that worked for one engineer over 43 sessions has friction points when you introduce parallel work, shared review responsibility, and the organizational dynamics of “we should be using AI.” What I told him was: start narrow, build the process before you scale it, and protect the review gate like your incidents depend on it, because they do. This post is the longer version of that answer.

Where Is Your Team Right Now?

Before talking about methodology, it’s useful to have a calibrated view of where your team currently sits. Dan Shapiro and Nate B Jones describe a five-level framework for AI coding maturity that maps the spectrum from basic autocomplete to fully autonomous development:

Level	Label	Human role	AI role
0	Spicy Autocomplete	Writes all the code	Autocomplete / search
1	Coding Intern	Reviews every line	Boilerplate on request
2	Junior Developer	Pair programs, reviews all code	Generates code collaboratively
3	Developer as Manager	Full-time code reviewer	Writes most code
4	Developer as PM	Writes specifications	Executes development
5	Dark Factory	Designs systems and patterns	Builds, tests, ships autonomously

Most engineering teams using AI tools today are at Level 2. They’ve enabled Copilot, they use Claude or ChatGPT in chat, they review everything the AI generates. That’s genuine progress, but it’s also the level where, as Nate Jones notes, many developers experience slowdowns rather than speedups: they’re reviewing AI-generated code they didn’t write, at the speed they can read, while the AI works at the speed it can generate.

The methodology in this series was designed to move from Level 2 to Level 3 reliably, and to point toward Level 4. The PR review loop is Level 3. Specification-first development is Level 4. Level 5 is not the goal for infrastructure with real availability and security consequences. The human review gate isn’t inefficiency. It’s the accountability mechanism.

Where you should aim: move your team one level up, not to the top. Level 3 to Level 4 is the most valuable transition for most teams in 2026.

The Methodology, Restated for Teams

Four practices made AI assistance productive across 43 sessions. Each one matters independently. Together they compound.

Bounded sessions. Every session starts with a defined scope and ends with a pull request. The output of an AI-assisted session isn’t a running change to a system. It’s a reviewable artifact. This is non-negotiable because it’s the only thing that keeps AI assistance auditable. In a team context, one engineer “holds” the AI session for a focused feature or fix. That engineer’s job is to scope the session, review the AI output as it’s generated, and produce a PR. The session ends when the PR is open.

The PR as the unit of work. The PR is what the team reviews, not the AI conversation, not a demo. Other engineers evaluate the PR the same way they would any other: does it do what it claims, does it follow team patterns, does it introduce risk? The AI provenance is relevant context but not a reason to apply a different review standard.

The human review gate. AI writes code. Humans merge code. Every time, no exceptions. The review gate is where organizational knowledge lives, capturing what the AI doesn’t know about your environment, your threat model, your operational constraints. This is discussed in more depth below.

Knowledge capture. At the end of each session, the decisions, failures, and new patterns get documented. Over time this accumulates into institutional knowledge that makes every subsequent session faster. It also makes the work legible to people who weren’t in the session.

Prompting Patterns That Work at Scale

Individual engineers learn their own prompting habits. Teams need shared patterns, a consistent vocabulary for how to get useful output from AI assistance that multiple people can apply without divergent results.

Four patterns that held up across the full series:

Context-first. Before asking for new code, show the AI the existing pattern. “We implement secrets this way [paste ExternalSecret example]. Apply this pattern to the new application.” Without the existing pattern, the AI will implement something plausible that doesn’t match your conventions. It’ll be correct enough to pass review if reviewers are moving fast, and wrong enough to cause friction later.

Constraints upfront. State what the AI cannot do before asking what to do. “No :latest image tags, all secrets via ExternalSecret, no hardcoded credentials, no wildcard chart versions.” These constraints belong in your team’s CLAUDE.md so every engineer starts every session with them in scope, but they’re worth stating explicitly for any session involving unfamiliar territory.

Options, not implementations. For decisions that matter, such as architecture choices, security model, and schema design, ask for options with trade-offs first. Don’t accept the first implementation the AI proposes for a decision you can’t easily reverse. “What are two or three ways to approach this, and what are the trade-offs for each?” is a better prompt than “implement X” when X has significant downstream consequences.

“What could go wrong?” Before merging any security-related change, prompt explicitly: “What edge cases or security concerns should I review in this PR?” The AI will surface things the implementing engineer may have normalized past. This isn’t a replacement for a human security review, but it catches a class of issues that fall through in normal code review because reviewers share the same blind spots as the author.

Building Team-Specific AI Tooling

The most durable investment is the tooling that makes AI assistance consistent across your team. This isn’t about prompt libraries or prompt templates. It’s about encoding your team’s engineering standards in a form the AI can use.

Team CLAUDE.md. Claude Code reads the CLAUDE.md at repository root at the start of every session. This is where you encode what’s established and what’s off-limits: your secret management approach, your image pinning policy, your naming conventions, your deployment patterns. Every engineer who opens a session in that repository starts from the same constraints. The CLAUDE.md is a living document. Update it when you discover a new pattern or a new foot-gun.

Domain-specific review prompts. Your stack has specific failure modes. The AI Code Review Action and any review workflow you build should have review prompts tailored to your known gotchas, not generic “review this code” prompts. For infrastructure work: “Does this expose any secrets in ConfigMaps rather than ExternalSecrets? Does this use a pinned image tag? Does this follow the team’s ingress pattern?” Writing these prompts forces your team to articulate what matters in review, which has value independent of the AI.

Skills for repeatable workflows. Claude Code supports custom skills, slash commands that encode multi-step workflows. Session start, session end, PR creation, knowledge capture: anything your team does repeatedly in a predictable sequence is a candidate for a skill. The return is consistency across engineers and sessions.

A team gotchas registry. The failures-as-documentation pattern is the highest-leverage knowledge capture practice. Every time AI assistance produces something wrong, whether a misconfigured resource, an incorrect API version, or a misunderstood constraint, that failure gets documented in a shared registry. The registry becomes the institutional memory of what the AI doesn’t know about your environment. It feeds back into the CLAUDE.md and the review prompts.

The Human Review Gate: Non-Negotiable

The review gate deserves its own section because it’s where teams most commonly break down.

The pattern that fails: the team starts using AI assistance, PRs get opened faster, review velocity doesn’t keep up, reviewers develop an implicit assumption that “the AI checked it” and reduce scrutiny. Six weeks later a misconfigured security policy merges because the reviewer assumed the AI would have flagged it.

The AI doesn’t know what it doesn’t know about your environment. It can implement patterns correctly in the abstract and incorrectly for your specific deployment. It can write code that passes every static check and misses an operational constraint that lives in the reviewer’s head.

Several practices keep the gate meaningful:

Security-relevant changes require extra scrutiny. Authentication configuration, credential handling, network policies, RBAC, secret management: any change touching these areas gets reviewed as if a junior engineer wrote it. Apply the review prompts explicitly. Check the AI’s work against your threat model.

Track failure modes. Keep a team log of AI mistakes and what caught them. This is the same data that feeds the gotchas registry, but framed as review analytics: how many security issues were caught in review? How many operational issues emerged post-merge? Over time this tells you where your review process needs more depth.

The reviewer is accountable. The engineer who approves and merges a PR is accountable for it, regardless of whether AI generated it. This isn’t punitive. It’s the thing that keeps review meaningful. If reviewers feel they’re checking AI output rather than approving a change, the quality of review degrades.

Measuring the Value

Don’t measure AI-assisted engineering by lines of code generated. That metric optimizes for volume, which isn’t the constraint.

Useful metrics:

Time from requirement to working PR. This is the output of a bounded session. If sessions are taking four hours to produce a PR that used to take two days, that’s a real signal. If sessions are taking four hours to produce something that would have taken four hours manually, the methodology needs examination.

PR revert rate. Track AI-assisted PRs separately. Are they more or less likely to need reversion than manually-written PRs? If the revert rate is higher, the review gate needs strengthening. If it’s equivalent or lower, you have evidence that the methodology is producing quality.

Knowledge base growth. How many gotchas are documented? How many review prompts are in the domain-specific library? How often does a new engineer say “I found the answer in the docs”? The knowledge capture output is a lagging indicator of methodology quality. Teams that capture well get faster over time. Teams that skip capture plateau.

Anecdotal velocity data. Ask engineers directly. Did AI assistance help you complete this? Was there a moment where you would have been blocked without it? Structured anecdotes aren’t rigorous data but they surface qualitative patterns faster than metrics.

To calibrate expectations: the project underlying this series covered 43 sessions, 185 PRs, and 20+ applications deployed with full SSO, HA, monitoring, and security scanning. The documentation, changelogs, gotcha registries, architecture references, was produced as a side effect of the methodology. That volume of work, with that level of documentation, isn’t achievable at the same pace without AI assistance. But it’s also not achievable without the methodology. AI without the session structure, review gate, and knowledge capture produces work that’s hard to audit and hard to build on.

When NOT to Use AI Assistance

This is the part most AI adoption guides skip.

Novel APIs without public documentation. The AI’s knowledge has a cutoff. For new APIs, proprietary systems, or anything with sparse public documentation, the AI will generate plausible-looking implementations that are wrong. You won’t catch this until you run the code. Use AI to scaffold structure and generate documentation stubs. Write the implementation manually with the actual docs open.

Security decisions that require threat modeling. Use AI to implement security controls. Don’t use it to design them. Security architecture requires organizational context, your threat model, your compliance requirements, your operational constraints, that the AI doesn’t have and can’t derive from a prompt. “What are the security implications of X?” is a useful prompt. “Design our authentication model” is not.

Irreversible operations. Production database migrations, destructive Terraform changes, any operation with significant blast radius and no rollback path: AI can scaffold, but a human must verify manually before executing. Read the generated SQL. Understand what terraform destroy will delete. Don’t execute irreversible operations just because the AI generated them and they look right.

When the human can’t evaluate the output. This is the honest constraint. AI assistance requires a human who can review the output and recognize when it’s wrong. If an engineer doesn’t understand the domain well enough to evaluate the generated code, AI assistance in that domain isn’t safe. The answer isn’t to skip review. It’s to pair with someone who can review, or to build the domain knowledge before using AI assistance in that area.

Team Adoption Model

Adopt in phases. Trying to roll out AI-assisted engineering team-wide before the methodology is validated locally produces inconsistent results and backlash when the first high-profile mistake occurs.

flowchart LR
    P1["Phase 1<br/>Experiment<br/>(1 engineer, 1 project)"]
    P2["Phase 2<br/>Expand<br/>(Team uses AI on PRs<br/>Review prompts established)"]
    P3["Phase 3<br/>Scale<br/>(Domain skills<br/>Knowledge base<br/>Routine capture)"]

    P1 -->|"CLAUDE.md built<br/>First gotchas documented<br/>Review prompts drafted"| P2
    P2 -->|"Review quality validated<br/>PR metrics baseline established<br/>Skills developed"| P3

Phase 1: Experiment. One engineer, one project, explicitly experimental. The goal is to build the team’s CLAUDE.md, draft the first set of review prompts, and start the gotchas registry. This engineer is making the methodology decisions that the rest of the team will inherit, so choose someone who understands your stack deeply and will write down what they learn. Phase 1 is complete when: (1) CLAUDE.md exists and encodes at least five project-specific conventions the AI consistently respects; (2) a gotchas registry has at least ten entries from real sessions; (3) the review prompt has been used on at least five PRs and has caught at least one real issue the human reviewer would have missed. These aren’t arbitrary thresholds. They’re the point at which the methodology has enough accumulated context to transfer to a second engineer.

Phase 2: Expand. PR review by AI becomes standard practice. Engineers use AI assistance for implementation in their domains. The review prompts are in place and the team knows how to use them. Metrics tracking begins. The CLAUDE.md is updated based on Phase 1 learning.

Phase 3: Scale. Domain-specific skills are built for your team’s repeatable workflows. Knowledge capture is routine. New engineers onboard into an environment where the methodology is documented and the gotchas are visible. The goal in this phase shifts from “how do we use AI assistance” to “how do we make AI assistance better over time.”

The goal throughout isn’t “AI does engineering.” It’s “engineers accomplish more with the same headcount.” The methodology is what makes that compounding, not the model.

The Collaboration Model

flowchart TD
    ENG["Engineer<br/>(Scope · Review · Merge)"]
    AI["AI<br/>(Implement · Scaffold · Suggest)"]
    PR["Pull Request"]
    REVIEW["Team Review<br/>(Human gate)"]
    MERGE["Merge to main"]
    KC["Knowledge Capture<br/>(Gotchas · Decisions · Patterns)"]
    CLMD["CLAUDE.md + Skills<br/>(Constraints · Context)"]

    CLMD -->|"Informs session"| ENG
    ENG -->|"Scopes session<br/>Provides constraints"| AI
    AI -->|"Generates implementation"| ENG
    ENG -->|"Reviews AI output<br/>Opens PR"| PR
    PR -->|"Team evaluates<br/>as normal PR"| REVIEW
    REVIEW -->|"Approved"| MERGE
    MERGE -->|"Session end"| KC
    KC -->|"Updates"| CLMD

The diagram is the methodology. What makes it different from ad-hoc AI use is the loop at the bottom: knowledge capture feeds back into the constraints and context that start the next session. The system gets better over time because failures and decisions are written down and made available to every subsequent session.

AI Collaboration Note What Claude contributed: The first draft of this post’s prompting patterns section was written with Claude. I described what had worked across 43 sessions and asked it to distill the patterns. It produced the four-pattern framework (context-first, explicit constraints, options not implementations, what could go wrong) in one pass. The framework was accurate. Where it needed correction: The initial draft presented the patterns as universal, without the caveats about when they fail. The “when NOT to use AI assistance” section and the “domain expertise required for review” caveat were both added by hand. Prompt that worked: “I’ve been doing AI-assisted infrastructure work for 43 sessions. Here are the prompting approaches that worked and why. Distill these into a framework a team could adopt.” Using a different AI tool? The framework transfers to any AI assistant. The key insight, that context-first prompting works because it forces the AI to reason about your specific constraints rather than solving a generic problem, applies regardless of model.

Five Lessons for Engineering Leaders

The methodology is more important than the model. Teams that have a clear process for scoping, reviewing, and capturing AI-assisted work get compounding returns. Teams that use AI ad-hoc get individual wins with no accumulation.

The review gate can’t be soft. If the human review gate degrades, if reviewers assume “the AI checked it,” you lose the thing that makes AI assistance safe to rely on. Protect the gate explicitly, especially when velocity pressures build.

The gotchas registry is your team’s unfair advantage. It encodes what the AI doesn’t know about your environment, your failure modes, and your hard-won configuration decisions. A new engineer who reads it before their first session gets months of context in an hour. An AI that can reference it makes fewer recoverable mistakes. This document compounds, but only if you write to it the day the failure happens, not the day you remember to.

Start narrow. One engineer, one project, one methodology. Validate before scaling. The engineers who adopt first become the internal experts who make Phase 2 work.

Track failure modes. What mistakes does AI assistance make in your domain? How are they caught? What slips through? The answers to these questions tell you where to invest in your review process and your CLAUDE.md. Teams that track this get better. Teams that don’t repeat the same failures across different sessions and different engineers.

Next: Post 16 — Lessons Learned and Future Work — closing the series: what worked, what I would do differently, and what comes next.