AI for Technical Leads & Architects

The Role Shifts

An individual developer using AI still owns the output: understanding it, checking it, and deciding whether to use it. Whether the complete task gets faster depends on the task, tool, and verification work.

At team level, faster draft generation can move work into review, integration, and maintenance. Watch for larger PRs, repeated convention violations, and design decisions accepted before their tradeoffs are understood. Measure whether those problems occur in your team rather than assuming a uniform productivity gain.

This guide proposes a leadership focus: make expectations and verification shared. Keep rules files, prompt templates, review checklists, and acceptance criteria close to the code. These provide a common reference; they do not make different AI sessions produce identical or correct answers. For example, if two PRs omit tenant checks, document the ownership rule and add an authorization regression case, then track whether that failure recurs.

Part 1: Code Review in an AI-First Team

Polished names, formatting, and comments are weak evidence of correctness, whether code was written by a person or generated. Review behavior, assumptions, and failure paths rather than treating a finished appearance as proof.

If draft volume grows faster than review capacity, keep PRs small, limit work in progress, and route changes by risk. Track queue time and rework before changing review depth.

What to Look For That AI Misses

Generated code can fail inside a function or at a system boundary. In addition to ordinary correctness checks, inspect the seams:

• Invented APIs — Does this library actually have this method? Hallucinated API calls look identical to real ones. If the import is unfamiliar, verify against the package documentation.
• Missing error propagation — Trace both successful and failed operations. Check that errors reach the right boundary without duplicate logs or leaked sensitive values.
• Auth and authorization gaps — Verify authentication and resource authorization independently. "Is the user logged in?" and "does this user have access to this resource?" are different questions.
• Architectural drift — Does this solution fit the existing patterns in the codebase, or does it introduce a parallel pattern? AI doesn't know your established conventions unless you tell it.
• Transaction boundaries — Check whether multi-step writes need one transaction and whether external side effects need a separate recovery policy. Ask: what happens if step 2 fails after step 1 succeeds?
• Stale dependencies — AI may reference packages, APIs, or approaches from its training data that are now deprecated or replaced. Check version-specific behavior.

Using AI to Review AI Code

A separate AI session can provide another review perspective. Give it the diff, relevant contracts, versions, and tests without the author's preferred conclusion. Ask for evidence-backed findings and missing context:

Compare this focused prompt with your ordinary review prompt on known examples. A fresh session can share the same blind spots and can invent findings. Verify each finding; absence of findings is not a security approval.

Structuring the PR Process for AI-Generated Code

Use a PR template that records verification and uncertainty regardless of authorship. If AI-assistance disclosure helps your team route review, the following is one possible policy:

## What this does
[one paragraph plain-language description]

## AI assistance used
- [ ] Generated from scratch by AI
- [ ] AI-suggested approach, human-written code
- [ ] AI-written with significant human modification
- [ ] Human-written with AI review/polish only

## Verification steps taken
- [ ] Checked changed or unfamiliar APIs against installed-version docs/types
- [ ] Tested relevant error paths; evidence linked below
- [ ] Checked authorization (not just authentication)
- [ ] Reviewed DB operations for transaction safety
- [ ] Security considerations noted below

## Areas of uncertainty
[What parts are uncertain? Where should the reviewer look hardest?]
[Link verification evidence; mark inapplicable checks N/A with a reason.]

The "areas of uncertainty" field is particularly valuable. Developers who used AI heavily often have genuine uncertainty about parts of the generated code. Making that uncertainty explicit directs reviewer attention efficiently.

Tiered Review Based on Risk

Define review depth by the change's possible effects. These tiers and reviewer counts are an example policy, not a measured optimum:

• Tier 1 — Deep review: Auth changes, database schema changes, security-sensitive code, payment flows, data export, admin functionality. Require two reviewers, manual testing of edge cases.
• Tier 2 — Standard review: New features, API endpoints, significant business logic. One thorough reviewer, happy and unhappy path testing.
• Tier 3 — Light review: Low-impact copy, isolated presentation changes, or routine test maintenance. Escalate tests that remove safety assertions, deployment/config changes, sensitive documentation, and UI changes affecting permissions or data exposure.

Classify PRs at creation time. The PR template can include a self-declared tier that reviewers can override.

Part 2: Team Workflows

Different developers can use the same tool with different context, verification habits, and permissions. Review actual examples to identify which differences matter before prescribing a common workflow.

Define shared context, permissions, and verification expectations, then calibrate them using actual PRs and incidents. Leave room for developers to choose tools within that policy.

The Team Context File

The tools below support project guidance through different mechanisms: CLAUDE.md for Claude Code, .cursor/rules/ for Cursor (the root .cursorrules file is the legacy form), .github/copilot-instructions.md for Copilot, and many tools also read a shared AGENTS.md. File names alone do not establish identical loading or precedence. Verify the supported feature, directory scope, and loaded instructions in each team tool.

A team context file can state the following. The example stack and testing rules below describe a fictional repository, not current version recommendations; replace them with your lockfile and actual policy:

• What stack you're on and what versions matter
• What patterns to follow and which to avoid
• What files or directories are off-limits for modification
• How error handling works in your codebase
• What logging and observability patterns to use
• What the testing conventions are
• Security-relevant constraints (never log PII, always validate external input)

# Team Context

## Stack
- TypeScript 5.x, Node.js 24, Express 5.x
- PostgreSQL 16 via Kysely (NOT TypeORM, NOT raw SQL except in migrations)
- Zod for all input validation — validate at every API boundary
- Vitest for unit tests, Supertest for integration tests

## Patterns to follow
- All route handlers are in `src/routes/`, thin handlers only
- Business logic lives in `src/services/`, never in routes
- Database queries in `src/db/queries/`, never inline in services
- Use Result types (ok/err) for expected service failures; translate unexpected
  infrastructure errors at the documented boundary

## Patterns to avoid
- Do NOT use `any` in TypeScript — use `unknown` and narrow
- Do NOT put business logic in middleware
- Do NOT use `console.log` — use the logger in `src/lib/logger.ts`
- Do NOT access `process.env` directly — use `src/config.ts`

## Security rules (non-negotiable)
- Never log request bodies that may contain passwords or tokens
- All external input must pass Zod validation before use
- Use parameterized queries — never string-concatenate SQL
- Auth middleware is in `src/middleware/auth.ts` — apply to protected routes
- Check resource/tenant authorization in the service before reading or writing

## Testing
- Every service function needs a unit test
- Every API endpoint needs an integration test against a real test DB
- Test file lives next to the file it tests: `foo.ts` → `foo.test.ts`

Commit project guidance with the code, then verify loading in a fresh session and the relevant feature. Claude Code loads applicable ancestor files at launch and nested files on demand; Cursor project rules use activation metadata and file scope. Copilot support varies by feature, and Copilot code review reads instructions from the PR head branch. Protect instruction changes through review. These files guide the model; enforce critical rules in code and CI. The teamwork guide covers the tool-specific loading checks.

Onboarding Developers to an AI-Augmented Workflow

New developers joining an AI-first team face a novel problem: they need to learn the codebase, learn the AI tools, and learn how the team uses AI — simultaneously. Without guidance, new developers can miss conventions or mistake tool access for permission to act. Make learning and verification expectations explicit rather than setting an AI-usage quota.

Build an explicit AI onboarding session into your process. It should cover:

• Which tools the team uses and how they're configured
• Where the team context file is and what it says
• What AI is trusted to do autonomously vs. where to verify carefully
• How the PR template works and what the uncertainty field is for
• Two or three canonical examples of good AI use in your codebase (real PRs)
• Two or three examples of AI failures caught in review (what to watch for)

Use examples from the actual codebase to make expectations concrete, and explain what was verified and what failed.

Sprint Planning and Estimation

Do not apply a fixed AI speed multiplier to estimates. METR's early-2025 randomized study found a slowdown for experienced contributors working in their own repositories; its 2026 follow-up warns that selection effects complicate newer measurements. Neither result predicts your team's current speed. Estimate implementation, verification, review, and integration separately, then compare estimates with actual work.

Use AI to improve planning, not just execution:

Use the response to identify questions for the team. Validate pagination, authorization, and cross-service assumptions in the code before turning an estimate range into a commitment.

Team AI Retrospectives

Add an AI-specific retrospective question to your regular sprint retros. Not "did we use AI?" but pattern-focused questions:

• What AI-generated code did we find problems with this sprint? What category of problem was it?
• Were there tasks where AI slowed us down rather than sped us up? Why?
• What prompt or pattern worked well that we should add to the team library?
• Did AI introduce any inconsistency with existing codebase patterns? How did we catch it?

These questions generate institutional knowledge: the team's collective learning about where AI works in their specific codebase. Feed the findings back into the context file and prompt library.

Part 3: Building an Organizational Prompt Library

Every developer on your team is solving overlapping problems with AI every day. They write prompts to generate tests, review security, document functions, debug errors, and plan features. Most of those prompts are written from scratch each time — inconsistent in quality, incomplete in context, and invisible to the rest of the team.

A shared prompt library changes this. Instead of each developer reinventing prompts individually, the team accumulates battle-tested prompts that are specific to your stack, your conventions, and the problems you actually encounter.

What Belongs in an Organizational Prompt Library

Individual prompts belong in individual workflows. Team prompts belong in the library. The distinction is whether the prompt depends on team-specific context — your stack, your conventions, your codebase patterns — or whether it's generic enough to work anywhere.

Good candidates for a team prompt library:

• Code review prompts that reference your specific security requirements
• Test generation prompts that follow your testing conventions
• Debugging prompts tuned to your logging format
• PR description generation prompts matching your template
• Documentation prompts that follow your doc style
• Architecture review prompts that reference your existing patterns
• Onboarding prompts for understanding unfamiliar parts of the codebase

Prompt Structure for Reuse

A prompt that works once in your own session often fails when a teammate uses it without the surrounding context you had. Reusable prompts need explicit structure:

# [Category]: [Purpose]
## When to use
[One sentence: what situation this prompt is for]

## Context to provide
- [What to paste or describe before using this prompt]
- [What information AI needs that isn't in the prompt itself]

## The prompt
[Prompt text with [PLACEHOLDER] markers for variable parts]

## Expected output
[What good output looks like — helps developers know when to regenerate]

## Known limitations
[Where this prompt fails or produces poor output — so teammates don't waste time]

The "known limitations" section is what separates a real team asset from a prompt someone wrote once and thought was good. Honest documentation of where a prompt fails saves teammates from discovering the same failure the hard way.

Example: Security Review Prompt

# Security: Pre-merge Security Review

## When to use
Before merging any PR that touches authentication, authorization,
data access, external API calls, or user input handling.

## Context to provide
Provide the relevant diff, installed versions, authorization/data-flow contracts,
and test evidence. Remove secrets and unnecessary personal data first.

## The prompt
You are performing a security review of this code change for a
[Node.js/TypeScript/Express] application.

Check specifically for:
1. SQL injection — check parameterized values. For Kysely, inspect sql.raw(),
   sql.lit(), and dynamic identifiers; do not treat raw strings as safe values.
   Require server-controlled allowlists for dynamic columns/tables.
2. Authorization gaps — code may authenticate (check JWT) but skip
   authorization (check that this user can access this resource)
3. Sensitive data in logs — we never log passwords, tokens, or PII
4. Input validation — all external input must pass Zod validation before use
5. Path traversal — any use of user-supplied strings in file paths
6. Mass assignment — are we accidentally exposing fields the user shouldn't set?
7. Credential verification — use the platform's password/token verification
   primitives; inspect secret comparisons and their surrounding error paths

For each finding: location, severity, supporting evidence, assumptions, and
proposed validation or fix. Separate confirmed defects from hypotheses.
Always list review scope, missing context, and checks not performed.

[PASTE DIFF HERE]

## Expected output
A numbered findings list followed by scope and unresolved questions.
If empty, say "No findings in the reviewed scope"; do not certify safety.

## Known limitations
- AI misses business-logic authorization errors where the check
  exists but applies the wrong rules
- Does not replace dependency vulnerability or license review
- Kysely identifier helpers such as sql.ref() are not parameterized values;
  review their inputs and installed-version contract, not only the method name
- A model review can miss defects and invent findings; validate both outcomes

Maintaining the Library

Give the library an owner, update triggers, and time for evaluation. Deprecate prompts that no longer fit the stack or fail their reference cases.

• Own it like code: The prompt library lives in the repository. Changes go through PR review. Version controlled, not shared in a Notion doc.
• Update triggers: When a dependency major-versions, review relevant prompts. When the retrospective surfaces a prompt failure, update it. When a new pattern is established, add a prompt for it.
• Quarterly audit: Once a quarter, run through each prompt. Test it against a current problem. Either validate that it still works or update/deprecate it.
• Contribution path: Every developer can submit a prompt. Prompts go through one review cycle before landing. The bar is: does it work consistently, does it have context documented, does it have known limitations noted?

Part 4: Architecture Decisions with AI

Architecture decisions are high-stakes, high-ambiguity problems. The right answer depends on your specific constraints — team size, existing system, performance requirements, organizational politics, budget. AI doesn't know any of these unless you provide them, and providing them takes deliberate effort.

The risk of using AI poorly in architecture is not that it gives bad advice — it's that it gives plausible-sounding advice that fits a different system than yours. A model can produce an argument for a familiar architecture while missing the constraints that make it unsuitable here. Supply those constraints and ask which evidence is missing.

The key is to make AI your adversary in the evaluation process, not your validator.

Exploring Options Before Deciding

A prompt that announces a preferred answer can bias the discussion. To examine alternatives, first describe constraints and decision criteria without naming your favorite.

Break this by asking for a structured comparison before revealing your preference:

The "do not recommend one" instruction requests comparison before selection; it does not guarantee that the options are complete or fairly represented. After you read all three, you can ask follow-up questions about the specific tradeoffs that matter for your context.

Challenging Your Own Decisions

When you've already made a tentative decision, use AI to stress-test it before you commit:

This prompt requests a failure analysis rather than a recommendation. Check proposed risks against evidence and ask for overlooked advantages separately. Candidate risks include table growth, query performance on wide JSON columns, the coupling between application transaction and audit write, the difficulty of replaying history, the schema-less nature of old/new JSON becoming unmaintainable over time. Some may matter for your system; others may be irrelevant or false. Test the consequential assumptions before building.

Architecture Decision Records with AI

An Architecture Decision Record (ADR) documents why a decision was made — not just what the decision is. This is exactly the kind of information AI can help structure, because the structure is consistent and the thinking has usually already happened in conversation.

AI drafts the ADR from the reasoning you've provided. You review it for accuracy and nuance — the AI won't know the full organizational context, the specific conversation you had with your team, or the regulatory constraint that made one option unacceptable. Add those details. The draft supplies structure; verify every asserted reason and consequence against the decision record.

Evaluating Third-Party Libraries and Services

Choosing a dependency is an architectural decision with a long tail. AI can help structure the evaluation, but its training data has a cutoff — library ecosystems change, companies get acquired, open-source projects go unmaintained.

The independent verification is work for the reviewer, not a guarantee produced by the note. Require current primary sources for version support, storage requirements, maintenance, and license metadata; record unknowns instead of accepting confident prose.

Part 5: Governance, Standards, and Quality

Governance is the word teams reach for when informal coordination stops working. Independent AI sessions can miss decisions made elsewhere in the team. Make those decisions discoverable and check whether generated changes follow them.

Governance doesn't require bureaucracy. It requires clarity: what decisions are made once and shared, what decisions each developer makes individually, and what happens when something goes wrong.

Coding Standards That Work with AI

A standards document can remain invisible to a coding session unless the tool loads it. Put concise operational guidance in supported instruction files, keep explanations accessible, and verify which files actually enter context.

Write operational guidance in the supported project file and keep the human-facing rationale nearby. This example changes the wording of a convention; it does not make the convention self-enforcing:

// Traditional coding standards document:
// "Prefer functional components and hooks in React.
//  Avoid class components except in legacy code."

// CLAUDE.md — the same standard as an AI instruction:
// New React components use functional components and hooks.
// Do NOT add new class components. If asked to modify existing
// class components, preserve their style unless a migration is approved.

Once loaded, the instruction form makes the convention available as model context. Keep the same policy readable for developers. Neither enforces anything on its own: add a lint rule (here, one that flags class components) so CI catches what both the model and the reviewer miss.

Managing Technical Debt from AI

Accepting generated code before the team understands it creates maintenance risk. That risk includes code whose rationale is unclear even when it passes tests. Record consequential design choices and make their assumptions reviewable.

Address this proactively:

• Require understanding before merging: Developers should be able to explain any AI-generated code in their PR. "AI wrote it and it works" is not sufficient. If they can't explain it, they need to dig in before merging.
• Tag AI-generated sections: Some teams annotate heavily AI-generated files or sections. This isn't shame — it's metadata that tells future maintainers the code may need extra review when refactoring.
• Debt sprint regularly: Schedule explicit time to revisit and understand AI-generated code that was merged under time pressure. This is maintenance, not cleanup — treat it accordingly.
• Prefer readable over clever: Instruct AI toward readability explicitly. Review for unnecessary abstraction and compressed logic. Your codebase benefits from obvious over clever, especially in AI-generated code where no human author will champion it when a future maintainer is confused.

CI Integration for AI-Generated Code Quality

Your CI pipeline is the last line of defense before merge. For AI-assisted teams, expand what CI catches:

• Type checking at strict mode: Use strict: true to strengthen checks against the installed declarations. It does not reject explicit any; use a rule such as @typescript-eslint/no-explicit-any when that is your policy. Assertions and any can hide mistakes, and type checking does not verify runtime authorization or business behavior.
• Dependency audits: Review dependency and lockfile diffs for unexpected additions. A vulnerability audit such as npm audit checks known advisories; it does not establish that a package is intended, trustworthy, or suitable.
• License compliance: Inventory dependency licenses and flag changes against the organization's policy. Automation supports review; it does not decide every compatibility question or make a license universally acceptable or unacceptable.
• Security scanning: Run SAST tools (ESLint security plugins, Semgrep) on every PR. Treat all code as requiring security verification. Match scanner rules to your stack and investigate findings; a clean scan is not proof of safety.
• Test coverage thresholds: Coverage thresholds measure which code was executed, not whether assertions would catch a defect. Review expected outcomes, test failure paths, and use targeted regression or mutation cases for consequential behavior.

Measuring Impact Without Measuring Output

Tracking developer productivity by lines of code written or PRs merged was always a bad idea. With AI, it becomes actively harmful: AI generates lines of code trivially, so raw volume metrics are meaningless or worse — they incentivize accepting AI output without review.

What to measure instead:

• Defect rate per feature: Are features shipping with fewer production bugs than before? This is the real quality signal.
• Time from spec to working feature: Measure the full cycle, including coding, verification, queueing, review, and rework. Compare similar work and record context rather than attributing every change to AI.
• Review revision rounds: If PRs routinely need multiple rounds of revisions, that's a signal of poor initial quality — from AI or from insufficient human review before submission.
• Escaped defects: Bugs that make it to production are expensive. Track them by type. If AI-related failures (hallucinated APIs, missing error handling) appear repeatedly, update your review process and context file.

Security Governance for AI-Assisted Teams

AI introduces specific security governance questions that didn't exist before:

• What goes into the AI context? Developers pasting sensitive data — customer PII, production credentials, internal architecture details — into an AI session that may be logged by the provider is a data governance risk. Define what's safe to share and what's not.
• Which AI providers are approved? Different providers have different data retention and training policies. Establish an approved list and a process for evaluating new tools before developers adopt them.
• How is AI-generated code reviewed for security? Use a tested review prompt as an aid on security-sensitive PRs, alongside human review and executable checks. Neither human nor model authorship establishes safety.
• Dependency vetting: AI suggests dependencies. Developers sometimes accept them without the vetting they'd apply to a dependency they chose themselves. Establish the same vetting process for both.

Part 6: The Technical Lead's Own Workflow

Everything above is about what you set up for your team. This section is about your own work — the places where AI changes how a technical lead or architect spends their time.

Unblocking Developers Faster

An AI-generated investigation outline can help prepare an asynchronous debugging handoff. Provide sanitized code, errors, and attempted fixes:

Check the proposed causes against the error and source, then send the developer the next discriminating experiment. Escalate to joint debugging when the outline depends on missing system context.

Reading Unfamiliar Code Quickly

Technical leads frequently need to understand code they didn't write, in a part of the system they haven't touched recently. AI can draft a module map to check against source and tests:

The "non-obvious behavior" clause is the valuable part. Ask for source locations for side effects, hidden state, temporal coupling, and order-dependent behavior. Check those claims and inspect important paths the model omitted.

Writing Technical Documents

Technical leads write a lot: ADRs, RFCs, post-mortems, onboarding docs, runbooks. These documents share a structure — context, decision or incident, analysis, outcome — that AI handles well once you provide the substance.

One workflow is to provide a verified incident record or discuss the known facts, then ask for a structured draft. Mark hypothetical examples and distinguish confirmed causes from hypotheses:

AI structures the post-mortem. You review it for accuracy, add the specific names and times, and adjust the action items to match what your team can actually commit to. Check each fact against the incident record and assign owners and dates to accepted action items. Do not treat an invented timeline or plausible preventive action as established evidence.

Staying Technically Sharp

Technical leads who stop writing code gradually lose the intuition that makes their judgment valuable. AI can be a tool for staying sharp without requiring large blocks of focused implementation time:

• Use a bounded prototype to test an architectural assumption and document which production constraints it omits
• Dig into unfamiliar corners of the codebase conversationally: "explain this module to me as if I've never seen it, then tell me what its tests are missing"
• Use official release notes and your lockfile as inputs when asking AI to summarize library changes; verify the proposed implications
• Use AI to draft code that you then read and critique — reading AI code with critical eyes develops intuition for what it does well and where it needs help

Sources and review scope

Rule locations and loading were checked against Claude Code memory, Cursor Rules, Copilot repository instructions, and the AGENTS.md convention. API and CI limits follow Kysely's Sql reference, TypeScript strict, no-explicit-any, and npm audit. METR's 2025 randomized study and 2026 follow-up have different measurement limits; neither supplies a speed multiplier for this team method. Sources checked Oct 29 2026; recheck by Nov 28 2026.

The five blocks are policy and prompt templates, not a runnable application. Small offline checks examined value binding and identifier/raw SQL construction with Kysely 0.28.8 and explicit-any behavior with TypeScript 7.0.2. They did not run a database, AI review, coding-tool UI, team workflow, or productivity experiment. The fictional stack, reviewer counts, prompt-library size, and audit cadence are examples to adapt and evaluate; they are not measured best practices.

Related Guides