[7] AI-Assisted Development: A Crash Course for Developers — Building a Structured Engineering Team with Claude Agents

📘 Part 7 of the Agentic Engineering Series

✍️By: David Estrada | 📅Date Published: 2026/05/15

We’ve come a long way together. We started with the fundamental fork between vibe coding and agentic engineering, worked through the discipline of specs, mapped out the full toolstack, and dug into how MCP gives agents real context. Now it’s time to tie it all together — here’s how you actually build the team that runs it.

AI-Assisted Development: A Crash Course for Developers

Building a Structured Engineering Team with Claude Agents

The Problem Every Developer Hits With AI

You start using an AI coding assistant. It feels like a superpower.

Then, a few weeks in, something breaks in production. You trace it back. The AI wrote that code. It looked fine. You reviewed it. You shipped it. But there was a subtle security issue in the input handling — something a thorough code review would have caught.

Or maybe you ask the AI to implement a feature, it tells you the tests pass, and you push. Later you discover the tests never actually ran because the test config had a silent misconfiguration. The AI reported success anyway.

These aren’t edge cases. They are the default failure mode of AI-assisted development when used without structure.

The AI is not the problem. The absence of process is.

This is a crash course on how to fix that — by building a structured, multi-agent development workflow. I’ll walk you through the architecture, the design decisions behind it, and what it changed about how I think about writing software with AI.

What Is AI-Assisted Development, Really?

If you are new to this space, here is a grounding definition.

AI-assisted development means using large language models as collaborators in your software development workflow. At the most basic level, that looks like autocomplete suggestions and inline code generation. At a more advanced level, it means asking an AI agent to implement entire features, write tests, review code, or deploy infrastructure.

Most developers today are somewhere in the middle: using AI for code generation but not yet trusting it to own end-to-end delivery. The gap between those two states is not model capability — it is workflow structure.

The Concept: An Engineering Team, Not a Chatbot

The shift that changes everything is this: stop thinking of AI as a single assistant and start thinking of it as a team with defined roles.

A professional engineering team has specialization. You do not ask your QA engineer to write deployment pipelines, and you do not ask your security auditor to own test coverage. Everyone has a domain, a responsibility, and a handoff protocol.

AI agents can work the same way.

The system described here is a Conductor architecture. It consists of one orchestrating agent and seven specialized subagents, each with a narrow, well-defined job. Sitting alongside the agents is a set of eleven skills — reusable behavioral protocols that enforce discipline at every step of the workflow.

Notice the two hard stops built in. The AI never auto-commits. You always have control at the moments that matter.

The Conductor: The Brain of the System

The Conductor is the orchestrator. It receives your feature request, classifies scope, breaks work down into EPICs, delegates to subagents, and tracks progress across a single source-of-truth file: docs/epics-status.md.

What the Conductor does not do is write code. That constraint is intentional. The moment an orchestrator starts implementing, it loses its objectivity as a coordinator.

Scope Lock: The First Gate

Before anything else, the Conductor classifies your request:

Bugfix or small change → handled immediately through a lightweight mini-cycle (implement → review → security check → tests → docs → commit message), without spinning up the full EPIC planning machinery.
EPIC-level feature → full Planning → Implementation → Review → Commit cycle.

This classification prevents a common AI failure mode: silently expanding a one-line bugfix into a refactor that touches fifteen files.

The Pre-Flight Spec Check

Before planning begins, the Conductor checks whether a spec already exists in docs/plans/. If the request is raw or vague, it invokes the spec-writer skill first and will not proceed to planning until a structured spec is confirmed. Implementation plans are built on clear, agreed requirements — not on the AI’s interpretation of a one-liner.

Session State

At every phase transition and before every subagent invocation, the Conductor writes docs/session/conductor-state.md — a machine-readable record of the current phase, last completed step, retry counts, blockers, and out-of-scope discoveries. Sessions are resumable and the Conductor never loses its place in a long multi-EPIC run.

Meet the Agents

Planning Subagent — Before a single line of code is written, reads the codebase. Uses semantic searches to find relevant files, identifies patterns and conventions, documents key functions to modify, and surfaces 2-3 implementation approaches. Explicitly restricted from writing plans or implementing anything. Read-only. Context only.

Implementation Subagent — Follows one non-negotiable rule: test-driven development. Write a failing test first. Write the minimum code to make it pass. Run the test — not assume it passes. Verify. Never runs git commit, git push, or any destructive git command. Committing is always the human’s responsibility. When it discovers out-of-scope work, it logs it rather than silently expanding.

Code Review Subagent — Examines the diff. Returns one of three verdicts: APPROVED, NEEDS_REVISION, or FAILED — with specific, file-and-line-referenced findings. Cannot implement fixes. A reviewer who can rewrite the code they’re reviewing is never fully a reviewer. If the Conductor receives NEEDS_REVISION twice on the same EPIC, it escalates to the user rather than absorbing the failure silently.

Security Subagent — Every EPIC cycle includes a security review as a required gate. Checks every changed file against the OWASP Top 10. Severity gating is strict: a CRITICAL finding blocks the entire EPIC. A MAJOR finding requires revision before proceeding.

Test Subagent — Owns coverage validation after implementation. Writes tests for all requirements and edge cases, runs the full regression suite to catch regressions. One hard constraint: cannot modify production code. Tests only.

Documentation Subagent — When any logic changes, audits and updates the README, API docs, inline comments (only for non-obvious logic), CHANGELOG, and architecture docs. Flags documentation gaps that require business context only a human can provide.

The Skills System: Reusable Workflow Protocols

Alongside the agents, the system includes eleven skills — enforced behavioral protocols that activate at specific moments. Skills make best practices structurally unavoidable rather than relying on everyone to remember them under deadline pressure.

🧠 /brainstorming — Before any creative work begins, requires exploring intent through collaborative dialogue. Proposes 2–3 approaches with trade‑offs. No jumping straight to implementation.

📋 /spec‑writer — Converts raw inputs into a structured feature spec with Goal, Requirements, Acceptance Criteria, Out‑of‑Scope, Assumptions, and Open Questions.

📝 /writing‑plans — Produces a comprehensive implementation plan broken into bite‑sized tasks (2–5 minutes each). Every task includes exact file paths, complete code, exact commands, and expected output. No vague “add validation here” placeholders.

⚙️ /executing‑plans — Executes written plans in batches of 3 tasks with a human checkpoint between each batch. Stops immediately on blockers rather than guessing through them.

✅ /verification‑before‑completion — The most critical skill in the system. No agent can claim success without running the verification command and showing the actual output. A direct countermeasure to AI’s most common failure mode — reporting that tests pass when they have not been run.

🐞 /bug‑logger — Captures bugs to docs/bugs/YYYY‑MM‑DD‑<slug>.md at any point without interrupting the current workflow. Deduplicates against existing bug files before creating new ones.

🎨 /frontend‑design — Creates production‑grade UI with an explicit mandate against generic AI aesthetics. Bold, intentional, context‑specific design is required.

📚 /update‑docs — Mandatory enforcement skill. No logic change is considered complete until the README accurately reflects it. The agent is blocked from finishing its turn if documentation is stale.

🧪 /webapp‑testing — Playwright browser automation for verifying frontend functionality, capturing screenshots, and inspecting console logs.

🗺️ /excalidraw‑diagram — Generates .excalidraw diagram files. Includes a render‑and‑validate loop to ensure the output is visually correct before it is considered done.

👥 /create‑agents‑md — Generates or refreshes AGENTS.md at the project root. Deep‑scans the codebase to auto‑populate as many sections as possible, then asks targeted follow‑up questions one at a time for anything it couldn’t infer.

AGENTS.md: The Project Context File Every AI Agent Needs

Here is a problem that comes up constantly in AI-assisted development: the agent does not know your project.

It does not know that you use Angular Signals instead of RxJS. It does not know that your build command is npm run build:prod not npm run build. It does not know about the linting step that must pass before any commit, or your firm rule against direct DOM manipulation, or that authentication goes through a specific service layer.

So it guesses. And when it guesses, it generates code that looks right but breaks your conventions — or worse, breaks your build.

AGENTS.md fixes this. You place it at the root of your project and it becomes the single source of truth that every AI agent reads before doing anything. A well-written AGENTS.md covers what the project is, the tech stack and frameworks, build/test/lint commands, project structure, coding standards, architecture decisions, available agents, and available commands.

For a new developer joining the project, AGENTS.md also serves as the fastest possible onboarding document — a single file that answers the questions that typically take a week of asking around to discover.

Giving AI Full Context: The Three-Layer System

AGENTS.md is the foundation, but project context for AI agents is organized into three complementary layers:

Layer 1 — AGENTS.md: Project-wide context for AI agents. Everything about your project that an agent needs before touching any code. Eliminates exploratory guesswork at the start of every session.

Layer 2 — A global instructions file: Repository-wide rules applied to every AI request. Use this for standards that apply universally — house style decisions, strict prohibitions, workflow reminders with no exceptions. Claude uses CLAUDE.md.

Layer 3 — Path-specific instruction files: Coding standards scoped to specific file types, applied automatically only when the agent is working on a matching file. This is where stack-specific rules live — Angular signal patterns, React hook conventions, .NET DDD layering rules.

All three layers are additive. When an agent works on an Angular file in a fully configured project, it has project-wide context from AGENTS.md, universal rules from CLAUDE.md, and Angular-specific standards from the matching path-scoped file — simultaneously.

Three Design Principles That Made the Biggest Difference

Human-in-the-loop at every commit boundary. The AI never pushes code. Every EPIC ends with a hard stop. You review the diff, you write the commit message, you decide whether to continue. The AI does the heavy lifting; you stay in control of what lands in your codebase.

Verification before any success claim. Every time AI-assisted development goes wrong visibly, it’s because someone trusted a reported success without verifying it. The /verification-before-completion skill closes this gap at the workflow level — not with a social norm that gets forgotten under deadline pressure, but with an iron rule that applies to every agent on every task.

Scope lock before scope work. The Conductor classifies every request before acting on it. Bugfix or EPIC-level feature? Raw idea or spec-backed requirement? These two classification steps prevent the silent scope creep that is responsible for most AI-assisted development disasters.

The Documentation and Tracking System

The system maintains structured state throughout a session:

docs/plans/YYYY-MM-DD-<feature>-spec.md — feature spec, written by /spec-writer
docs/plans/YYYY-MM-DD-<feature>-plan.md — implementation plan
docs/epics-status.md — single source of truth for all EPIC progress
docs/epics/epic-{N}-{task-name}.md — per-EPIC tracking file with task status table
docs/session/conductor-state.md — real-time conductor state
docs/bugs/YYYY-MM-DD-<slug>.md — bug log files
docs/plans/<feature>-complete.md — final completion report

This structure means that a session interrupted mid-EPIC can be resumed from an exact known state, and the full history of what was done — and why — is preserved in the repository alongside the code.

Getting Started

You do not have to adopt everything at once. A practical starting point:

Run /create-agents-md — generate an AGENTS.md at the root of your repository. This is the foundation. Everything else builds on the context it provides.
Add path-specific instruction files for your stack — so the agent follows your conventions automatically when editing technology-specific files.
Add /verification-before-completion — this skill alone will eliminate a whole category of false positives where the AI claims work is done without running the verification command.
Invoke the Conductor agent when you are ready to delegate larger features end-to-end.

The system is designed to be adopted incrementally. Start with context (AGENTS.md), add discipline (verification), then add orchestration (Conductor) when you’re ready for full end-to-end delegation.