DEV Community: Harshit Rathod

Beyond Vibe Coding: From AI-Assisted Coding to Agentic SDLC Automation

Harshit Rathod — Sat, 12 Sep 2026 15:52:54 +0000

Hook: Vibe coding works beautifully right up until it doesn't. You prompt, you skim, you accept, you move on — and it's genuinely faster, for a while. Then you hit a feature that spans fifteen repositories, and the model confidently puts the table in the wrong service.

The problem was never the model's code. It's that nobody decided which repository owned the change, which endpoints were needed, or in what order twelve tickets had to merge so nobody's branch conflicted. That decomposition work is the engineering — and it's the part vibe coding has no answer for.

Note: This describes the architecture of an internal engineering tool. Product specifics, repository names, and proprietary conventions are generalized. The patterns transfer; our config files wouldn't.

Agentic SDLC at a Glance


What it is	An AI development agent that takes a blank Jira story and returns a stack of reviewed merge requests
What it replaces	Ad-hoc prompting (vibe coding) for work that spans multiple repositories
What it automates	Planning, ticket decomposition, dependency ordering, TDD implementation, code review, MR creation
Execution order	DB → Backend → Shared UI → App UI → E2E → Review → MR
Human gates	2 — plan approval, and per-ticket approval. Nothing else requires a human
Architecture	Agentic CLI plugin + MCP tool server + prose workflow rules + on-demand skills + multi-model routing
Guardrail model	Independent model review of tests and code; 5-failure stop; no work on unapproved tickets
Implementation size	~7,800 lines, almost entirely English prose
Scale measured	35+ stories · 500+ tickets · ~11,400 tests · ~86% line coverage
Impact measured	~1,650 manual hours avoided (~90% of estimated manual effort)
Longest unattended run	~12 hours

Key Takeaways

Vibe coding doesn't scale past a single repository. It optimizes the step that was never the bottleneck: typing the code. Decomposition, sequencing, and verification are what actually consume the calendar.
Decomposition, not code generation, is the bottleneck in multi-repo development. An AI coding assistant that only writes code solves the easy half.
An AI development agent is not just an LLM. It's LLM reasoning + deterministic orchestration + curated context + skills + rules + tools + verification. Remove any one and it stops being trustworthy.
Your agent's business logic should be prose, not code — a workflow contract read fresh at the start of every run, changed via pull request.
Choose determinism over parallelism. A single linear dependency chain guarantees exactly one ticket is ready at a time, which makes an autonomous loop trivially correct.
Stacked branches keep AI output reviewable. One MR per ticket, each targeting its predecessor's branch. Reviewability — not generation speed — is the real bottleneck.
A model that writes both the tests and the code will write tests its code passes. Independent review by a different model is what breaks that loop.
Measured results: 35+ stories, 500+ tickets, ~1,650 manual hours avoided, ~11,400 tests at ~91% line coverage, longest unattended run ~12 hours.

Quick Answer: What Is Agentic SDLC Automation?

Agentic SDLC automation is the practice of giving an AI system ownership of a complete software delivery workflow — requirement intake, planning, task decomposition, implementation, testing, and code review — under deterministic orchestration and explicit verification gates, rather than generating code on request. The distinction from vibe coding is scope and accountability: a prompt answers "write this function," an agentic system answers "deliver this story, in the right repositories, in the right order, with tests someone reviewed."

Ours takes a blank Jira story key plus context and returns a stack of reviewed merge requests. It fetches the latest code from every affected repository, drafts a plan, writes one markdown file per proposed ticket for local review, publishes the plan to the wiki, and stops. You say LGTM. It creates the child tickets as a single linear dependency chain and stops again. You approve tickets. It then develops each in strict order — DB → Backend → Shared UI → App UI → E2E — writing tests first, getting them reviewed, implementing, getting the code reviewed, and opening one merge request per ticket on stacked branches.

Two human gates. Everything between them is autonomous.

Vibe Coding vs AI Coding Assistant vs Agentic SDLC

These are three points on one progression, not three competing tools. Each solves the bottleneck the previous one exposed.

Dimension	Vibe coding	AI coding assistant	Agentic SDLC automation
Unit of work	A prompt	A function, file, or diff	A story, decomposed into tickets
Who decomposes	Nobody — you improvise	You do, before prompting	The agent proposes; you approve
Task ordering	None	None — you sequence it	Dependency-aware execution chain
State across steps	Chat history	Conversation context	Ticket board + branches + MRs as durable state
Repository awareness	Whatever's open	The open file or workspace	Explicit repo map, module ownership, shared-library rules
Verification	Vibes — you skim and accept	You run the tests	Tests written first, reviewed by a second model, gated
Failure behavior	Silently wrong, found later	Returns a wrong answer confidently	Stops after 5 consecutive failures, posts a blocker
Output	Code in your editor	Code you paste	Stacked merge requests with test evidence
Human role	Accept or re-prompt	Prompt and review each output	Approve at two gates; review MRs
Scales to	One repo, one developer	One repo, one task at a time	A story spanning many repositories

Vibe coding removed the friction of typing code. Assistants removed the friction of writing correct code for a scoped task. Neither touched the part that actually consumes a sprint: deciding what the tickets are, which repository each belongs to, what order they merge in, and whether the result is trustworthy.

Definition — Agentic SDLC automation: A software delivery workflow in which an AI system executes planning, decomposition, implementation, testing, and review under deterministic orchestration, with explicit human approval gates and automated verification — as opposed to ad-hoc prompting with human-only review.

Definition — Autonomous development loop: A control loop that polls a ticket system for the next ready task, executes a full development workflow against it, and repeats without human input until every task is complete or a guardrail halts it.

Why Vibe Coding Stalls at the Repository Boundary

Vibe coding has a real domain where it wins. One repository, one developer, a task you could have scoped in your head anyway — prompt, skim, accept, move on. The loop is fast because the coordination cost is zero.

That cost is not zero in a microservices monorepo, where one feature is never one change. A single story routinely means:

2–3 database migrations across different services
8–10 backend endpoints in two or three repositories
Several new shared UI components, plus the pages consuming them
API integration work per endpoint on the frontend
End-to-end coverage per user journey

Each of these lives in an independent Git repository — its own main, its own CI, its own merge queue. Landing them in the right order without merge conflicts or half-integrated states is a coordination problem long before it's a coding problem.

Give a coding assistant the ticket "Add crop planning" and it will confidently start writing something. The question it can't answer alone is which repository, which module, which order, and what does this depend on.

This is where the vibe-coding loop inverts. Accepting a plausible diff is cheap; discovering three days later that the migration landed in the wrong service is not. The faster you generate unverified code across repository boundaries, the more expensive the correction becomes — you're not saving time, you're borrowing it at interest.

Every under-specified ticket you hand an agent is a ticket where it guesses — and a guess in ticket #3 propagates through tickets #4 through #12.

Where the Work Actually Goes

Before building anything, we looked at where the hours went. Across the ticket types the agent now generates, the distribution is lopsided in a useful way:

Ticket type	Count	Share	Character of the work
UI (incl. shared components)	128	43%	Highly patterned — forms, tables, modals, API wiring
Backend endpoints	105	35%	Highly patterned — controller, service, DTO, validation
Database migrations	42	14%	Convention-heavy, high blast radius if wrong
E2E journeys	24	8%	Scenario design, then mechanical execution

Roughly 78% of tickets are backend endpoints and their frontend integration. That's repetitive, convention-bound work where the decision space is narrow and the right answer is largely determined by what the codebase already does.

That's precisely the shape of work an agent handles well — if it's given a tight enough specification. Which brings us back to decomposition.

The Anatomy of an AI Development Agent

The most common misconception is that the model is the system. It isn't. In our experience the LLM is one of seven components, and it's not the one that determines whether you can trust the output.

Component	Role	What breaks without it
LLM reasoning	Planning, decomposition, implementation, review judgment	Nothing works at all
Deterministic orchestration	Fixed step order, dependency chain, state machine	Non-reproducible runs; conflicting concurrent work
Curated context	Repo map, latest code fetched before planning	Confident placement of code in the wrong service
Skills	Stack conventions loaded on demand	Output that passes tests but violates house style
Rules	The workflow contract, read fresh every run	Behavior drifts from what the team agreed
Tools (MCP)	Typed access to ticketing, wiki, git hosting	Malformed API calls; no audit boundary
Verification	Independent review of tests and code, hard gates	Plausible code with worthless tests

Definition — Agent orchestration: The deterministic layer that decides what runs next and in what order, leaving the LLM to decide how each step is performed. Orchestration is ordinary code and configuration — not model output — which is what makes agent behavior reproducible.

The split that matters: deterministic workflow, LLM reasoning. Step order, dependency resolution, branch topology, gate enforcement, and stop conditions are all deterministic. Design judgment, code, tests, and review opinions come from the model. We never let the model decide whether to run a gate — only what it concludes inside one.

Architecture Layer 1: An Agentic CLI Plugin, Not a Service

The agent ships as a plugin for an agentic coding CLI. This was the single highest-leverage decision.

It inherits, for free: filesystem access, shell execution, git, a permissions model, session management, and model routing. We wrote zero infrastructure code.

dev-agent/
├── commands/          # slash commands — the entry points
├── rules/             # the workflow contract (authoritative)
├── skills/            # stack conventions, loaded on demand
├── dev-tools-mcp/     # MCP server — ticketing, wiki, git hosting
└── Plans/             # generated artifacts, reviewed by humans

The whole thing is roughly 7,800 lines — and almost all of it is English. The only real code is a ~1,200-line MCP server wrapping three REST APIs.

In an agentic architecture, your business logic is prose. Leverage comes from the precision of your contract, not the cleverness of your implementation.

Architecture Layer 2: MCP as the Tool Boundary

The agent reaches external systems through a single Model Context Protocol server exposing 44 tools.

Domain	Tools	Responsibility
Ticketing	22	Read/update stories, create children, link dependencies, poll status, transition, comment
Wiki	12	Search, read requirement docs, publish approved plans
Git hosting	7	Branch existence, branch creation, MR create/get/list

Why not just let the model shell out to curl?

Typed contracts. Each tool has a schema. The model cannot mis-shape a payload.
A real audit boundary. Every external mutation flows through one surface you can log, permission, and rate-limit.
Failure containment. An API change breaks one Python function, not a hundred lines of prompt.
Least privilege. The server exposes exactly the operations the workflow needs. There is no generic "make an HTTP request" escape hatch.

Git is the deliberate exception — it runs through the shell, because git is already a precise CLI and the agent must operate inside whichever submodule it's working in.

Architecture Layer 3: Rules as a Contract, Read Fresh Every Run

rules/ holds the workflow specification, and the agent reads it at the start of every single run. Not fine-tuned. Not buried in a system prompt. Read fresh.

Rule file	Role
`workflow.md` (644 lines)	The full contract — step order, both gates, TDD discipline, the 5-consecutive-failure stop, the 30-minute re-read rule, status flow
`repositories.md` (206 lines)	Repo map, in-scope submodules, domain-module discovery, chain order, stacked-branch mechanics, MR targeting
`review-tests.md`	Test-review checklist — the gate before any implementation is written
`review-code.md`	Code-review checklist — the gate before a ticket reaches In Review
`wiki-template.md` (332 lines)	Required structure of the published requirement doc

Rules are layered and overridable: the agent checks for a project-level override before falling back to the plugin default. A team with stricter conventions overrides one file instead of forking the agent.

Rereading the contract every run sounds wasteful. It's the opposite. Changing agent behavior becomes a pull request against a markdown file — reviewable, diffable, revertible. No retraining, no redeploy, and no version skew between what the agent believes and what the team agreed.

Architecture Layer 4: Skills Loaded on Demand

Stack conventions live in skills that load only when the agent touches matching files.

Skill	Loads when	Covers
`db`	editing `.sql` migrations	Naming, UUID v7 keys, mandatory per-tenant partitioning, tenant-leading indexes, Flyway, rollback discipline
`java`	editing `.java`	Package layout, REST resources, DTOs/mappers, CDI, exception handling, red-green-refactor
`java-test`	writing JUnit	One behaviour per test, given/when/then, mocking strategy, naming format
`react`	editing `.tsx`	Component structure, hooks, state, forms, accessibility, shared-component placement
`react-test`	writing RTL tests	Strategy by component type, query hierarchy, mocking, async patterns
`jira`	any ticket operation	Search, create, update, transition, comment

This is progressive disclosure applied to context. The DB ticket never loads React conventions. The E2E ticket never loads migration rules. Context relevance, not context volume, is what degrades over a long run.

Why On-Demand Conventions Matter More Than They Sound

Our platform is multi-tenant on a single database, so every table must be partitioned by tenant. That one rule cascades into consequences that are not obvious:

Partitioned tables can't carry a simple primary key — so identity is a single UUID v7 column with no primary key constraint
Uniqueness becomes a unique index that must lead with the tenant column
There's no default partition, so writes for an unprovisioned tenant fail loudly instead of silently landing in a catch-all

That's a chain a new engineer gets wrong on their first migration, every time. Written down once, it's enforced across all 42 DB tickets without anyone remembering to check.

Architecture Layer 5: Model Routing by Cognitive Load

Not every step deserves the same model.

Stage	Model tier	Rationale
Planning & decomposition	Frontier / reasoning	Highest-leverage step; an error here propagates through every downstream ticket
Test review	Frontier / reasoning	Adversarial judgment — is this test real or tautological?
Code review	Frontier / reasoning	Same
Implementation (all types)	Fast / balanced	Constrained by tests already written and reviewed

The insight: implementation is the cheap part when the specification is tight. Once tests exist and a strong model has reviewed them, writing code that passes is comparatively mechanical. Spend your reasoning budget where judgment compounds.

Dependency-Aware Execution: One Chain, Not a Tree

Every generated ticket is blocked by exactly one predecessor and blocks exactly one successor.

DB1 → DB2 → BE1 → BE2 → BE3 → UI-C1 → UI-C2 → FE1 → FE2 → E2E1

No fan-out. Ever.

Definition — Dependency-aware execution: Ordering generated tasks so each begins only after the work it builds on is complete, so the agent never implements against code that doesn't exist yet.

A dependency DAG would be more "correct" — plenty of these tickets could genuinely run in parallel. We chose the chain anyway, because it guarantees one property worth more than theoretical throughput:

At most one ticket is ready at any moment.

That single invariant eliminates a whole class of failures: no two agents editing the same file, no duplicated shared components, no conflicts between sibling branches, no "which of these three branches has the migration?" archaeology. The loop that picks the next ticket becomes trivially correct — find the one approved ticket whose single predecessor is done.

Parallelism is a tempting optimization. Determinism is what makes an autonomous system trustworthy enough to leave running for twelve hours.

The Execution Order, and Why It's That Order

DB — migrations first, because every layer above depends on the schema existing
Backend — endpoints against the committed schema, one ticket per endpoint
Shared UI — common components land in the shared library before anything consumes them
App UI — pages and API integration, consuming those components rather than rebuilding them
E2E — user journeys against the real stack, once there's a stack to test
Review — independent model review at the test gate and the code gate, per ticket
MR — one merge request per ticket, stacked on its predecessor's branch

Stacked Branches: One MR Per Ticket

Within each repository, every ticket branches from its same-repo predecessor.

main
 └── STORY-100                    (integration branch)
      └── TICKET-101              MR → STORY-100
           └── TICKET-102         MR → TICKET-101
                └── TICKET-103    MR → TICKET-102

Each ticket's MR targets its predecessor's branch. When all child MRs merge into the integration branch, one final MR takes STORY-100 → main.

The payoff is reviewability. A reviewer opening TICKET-102 sees only that ticket's diff — not the migration from TICKET-101 underneath it. Without stacking, the last MR in a chain of twelve shows the cumulative diff of all twelve, and review collapses into rubber-stamping.

Generating code faster than humans can meaningfully review it isn't a throughput gain. It's risk, relocated downstream.

Verification and Guardrails Instead of Blind Autonomy

Autonomy without verification is just vibe coding at machine speed. That's the trap worth naming: an agent that plans, decomposes, and implements without gates doesn't fix the accept-and-move-on problem — it industrializes it. Every ticket runs strict TDD with two mandatory review gates:

Write tests → [GATE] → Implement → Tests pass → [GATE] → MR

The reviewing model emits either APPROVED or CHANGES REQUESTED: with a numbered, file-referenced list, and the implementing agent revises and resubmits.

The test-review checklist carries most of the value. It explicitly hunts the failure mode that makes AI-generated tests worthless:

No tautological tests — asserting a mock returned what it was told to return proves nothing
Specific assertions — not "no exception thrown" but actual value checks
No flaky waits — no sleep(N)
Realistic test data — not "abc" / 123
Explicit coverage of validation, authorization, edge cases, and state transitions

The code-review checklist adds scope discipline (no unrelated changes, no opportunistic refactoring) and a security pass (no sensitive data logged, no internal errors leaked, server-side validation, auth on every endpoint, tenant isolation preserved).

The Full Guardrail Set

Guardrail	Behavior
Test gate	No implementation begins until a second model approves the tests
Code gate	No MR opens until a second model approves the implementation
Approval gate	The agent never touches a ticket a human hasn't moved to approved status
5-failure stop	Five consecutive failing test runs halts the ticket and posts a blocker comment
30-minute re-read	Long-running tickets trigger a re-read of the original requirement before continuing
Scope discipline	Review rejects changes outside the ticket's stated scope
Local-first artifacts	Plans and tickets are markdown files before they're board state

A model that writes both the tests and the code will happily write tests its code passes. Independent review is the only thing that breaks that loop — and it's why the test numbers below mean something instead of being coverage theater.

Measuring the Impact

From production use on a real microservices platform (~15 active repositories, Java/Quarkus backends, React frontends):

Metric	Value
Feature stories planned end-to-end	35+
Child tickets generated & developed	500+
Manual development hours avoided	~1,650 hrs
Manual estimate vs. agent time	~2,480 hrs → ~835 hrs
Share of manual effort removed	~90%
Tests written	~11,400
Line coverage across services (sampled)	~86%
REST endpoints shipped	156
DB tables shipped	92
E2E user journeys	19
Longest unattended run	~12 hours

Test breakdown, counted directly from the test suites: ~5,325 backend unit tests (405 test classes) and ~6,052 frontend unit/component tests (591 test files), plus 19 E2E journey suites running against the real stack — real database, real backend, real UI, no mocks.

Reading These Numbers Honestly

Benchmark sections are usually where rigor goes to die. Four caveats worth stating plainly:

The test count and coverage are counted, the hours are extrapolated. Test cases (~11,400) and file/line counts came directly from the test suites and source trees. Line coverage (~86%) is a weighted average from JaCoCo reports that exist for a sample of backend modules, not a full-suite run across all 19 repositories — real data, partial coverage of the estate.

The 1,650 hours is a scaled comparison against estimates, not a controlled trial. The underlying ratio — roughly 90% of estimated manual effort removed, i.e. manual time running about 3x agent time — was established on an earlier, smaller slice of delivered work and held steady as ticket volume grew past 500. Applying that same ratio to the current scale gives ~2,480 estimated manual hours against ~835 hours of actual agent time. The manual side is an engineering estimate, defensible because these are ticket types the team has sized for years, but nobody built the same 500+ tickets twice to confirm it.

The ~90% figure measures effort removed, not effort eliminated. Those ~835 agent hours aren't free — they include human review at both gates, MR review, and intervention when a run stalls. What shrank is the manual writing of migrations, endpoints, components, and tests.

~86% line coverage is a floor claim, not a quality claim. Coverage measures execution, not assertion quality. What makes it meaningful here is the review gate: every test set was reviewed for tautologies and weak assertions before implementation existed.

Lessons Learned: Mistakes That Cost Us Time

Each of these looked reasonable and quietly made the system worse.

Letting the agent create the parent story. It now receives a blank story key to populate. Humans decide what gets built; the agent decides how it decomposes. That boundary turned out to be load-bearing — for trust as much as correctness.

Parallelizing development. Our first version modeled dependencies as a DAG and ran ready tickets concurrently. Merge conflicts and duplicated shared components ate the entire speedup and then some. The linear chain is slower on paper and faster in practice.

Writing tickets straight into the tracker. Wrong decomposition meant deleting tickets, unlinking dependencies, and cleaning up a polluted board. Now the plan and every proposed ticket are written as local markdown first, iterated with the developer, and pushed only after approval. Iterating on a file is free; iterating on a ticket board is not.

Bundling tickets to reduce count. "One ticket for the CRUD API" seems efficient. It produces an enormous diff, an unreviewable MR, and a ticket that's half-done for three days. The rule is now aggressively granular: one ticket per schema, per endpoint, per page, per integration, per journey.

Assuming the model would infer repository layout. It doesn't, reliably. The repo map, module conventions, and shared-component rules are written down explicitly — and the agent re-fetches the latest code from every affected repository before planning, so it plans against what's actually there rather than what it remembers.

Walkthrough: One Story, End to End

Here's what a typical run looks like from the outside.

Input — a blank story key plus context: an existing repo, a PRD, some design notes.
Plan — the agent fetches latest code across affected submodules, asks clarifying questions, and drafts a plan plus one markdown file per proposed ticket. Each records its target repo, target module, dependency, acceptance criteria, and verification scenarios.
Publish — the plan goes to the wiki. Cheap and reversible.
Gate 1 — you read the markdown locally and iterate. Nothing has touched the ticket board yet.
Create — on approval, ~12 child tickets are created in Triage and linked as one linear chain.
Gate 2 — you validate each ticket and approve it. The agent will not touch an unapproved ticket.
Develop — the loop polls for the one ready ticket, runs the matching workflow (DB / Backend / UI / E2E), and repeats. Each ticket: tests → review → implement → tests pass → review → stacked MR.
Integrate — once all tickets are in review, one integration MR per repository lands the stack.

The half-day unattended stretch happens between steps 7 and 8 — polling, developing, and opening MRs with nobody watching.

The Pattern, Generalized

Strip out the domain specifics and this applies to any team doing multi-repo development against a ticketing system:

Build on an agentic runtime, not from scratch. Filesystem, shell, git, permissions, model routing — already solved.
Put external integrations behind MCP. Typed, auditable, least-privilege, independently fixable.
Write the contract in prose; read it fresh every run. Behavior changes become pull requests.
Layer rules so projects override without forking.
Load stack conventions on demand. Context relevance beats context volume.
Route models by cognitive load. Reasoning for planning and review; fast models for constrained implementation.
Choose determinism over parallelism. A linear chain makes an autonomous loop trivially correct.
Stack your branches. Reviewability is the real bottleneck.
Make review gates hard blocks — reviewed by a different model than the one implementing.
Keep humans at the decomposition gate and the approval gate. Autonomy between, judgment at the boundaries.

FAQ

What is vibe coding, and when does it stop working?
Vibe coding is prompting an AI for code and accepting it on plausibility rather than verification. It works well for one repository, one developer, and tasks you could have scoped yourself. It stops working when a change spans repositories — because the hard part is no longer writing the code, it's deciding where the code belongs and in what order pieces must land.

What is agentic SDLC automation?
A delivery workflow where an AI system executes planning, decomposition, implementation, testing, and review under deterministic orchestration, with explicit human approval gates and automated verification. The defining trait is accountability for a story, not a diff.

How is an AI development agent different from an AI coding assistant?
An assistant makes you faster at a task you've already scoped. An agent does the scoping: it decides which repository and module each change belongs in, generates the ticket breakdown, orders the work by dependency, and produces reviewable merge requests. See the comparison table above.

Is an agentic SDLC just vibe coding with more steps?
No — the difference is what happens to unverified output. Vibe coding accepts code on plausibility. An agentic system cannot: tests are written and reviewed by an independent model before implementation exists, code is reviewed before an MR opens, and no ticket is touched until a human approves it. Remove those gates and you do get vibe coding at higher volume, which is worse than doing it by hand.

Does this replace developers?
No. It removes the manual writing of highly-patterned code and stops decomposition from being the thing that gets cut when a sprint is tight. Humans still decide what gets built, review every plan, and approve every ticket and merge request.

Why a linear dependency chain instead of parallel execution?
Because the invariant "exactly one ticket is ready at a time" eliminates merge conflicts, duplicated shared components, and concurrent edits to the same file. We tried parallel first. The conflicts cost more than the parallelism saved.

How do you stop an AI agent from writing tests that pass trivially?
A different model reviews the tests before any implementation exists, against a checklist targeting tautological assertions, vague "no exception thrown" checks, sleep() calls, and unrealistic test data. The implementing model never reviews its own tests.

What happens when the agent gets stuck?
It stops. Five consecutive test failures halts the ticket and posts a blocker comment rather than thrashing. Tickets running long trigger a re-read of the original requirement before continuing.

Isn't 7,800 lines of prose harder to maintain than code?
It's easier. It diffs, it reviews in a pull request, and any engineer can read a proposed workflow change without knowing the implementation. There's no retraining step and no gap between what the team agreed and what the agent does.

How much context does an agent like this need?
Less than you'd expect, if you're deliberate. Conventions load only when relevant — the DB ticket never loads frontend rules. Curated context beats large context: the repo map and freshly-fetched code prevent far more errors than a bigger window would.

Can this work outside a monorepo?
The decomposition, review-gate, and model-routing patterns are repo-agnostic. The stacked-branch and single-chain mechanics assume multiple coordinated repositories — in a single-repo project they simplify considerably but still help reviewability.

What's the minimum viable version of this?
A written workflow contract, one typed tool boundary to your ticket system, and an independent review gate before code is accepted. Dependency chaining and stacked branches matter once a story spans more than a couple of repositories.

Key Takeaways (Recap)

Vibe coding optimizes typing speed — never the actual bottleneck past one repository
Decomposition is the bottleneck in multi-repo development, not code generation
An AI development agent is LLM + orchestration + context + skills + rules + tools + verification — not a model alone
Deterministic orchestration decides what runs next; the LLM decides how
Determinism beats parallelism when you want to leave a system running unattended
Stacked branches keep AI output reviewable; reviewability is the real constraint
A different model must review the tests, or the tests are worthless
~1,650 hours avoided across 500+ tickets, ~11,400 tests at ~86% coverage, ~12 hours unattended

Conclusion

The most surprising thing about building this was how little of it is code. The agent is ~7,800 lines, and the meaningful part is a workflow contract written in English — precise enough to execute, readable enough that any engineer can review a change to it in a pull request.

We didn't build a system that writes code. We built a system that holds a specification precisely enough that writing the code becomes the easy part — then put a human at each end of it.

The twelve-hour unattended run is the part people react to. But that isn't a claim about model capability. It's a claim about specification quality: the agent ran that long without help because the contract was tight enough that there was nothing left to ask.

The path from vibe coding to an agentic SDLC isn't a better model or a longer context window. It's the unglamorous work of writing down what your team already knows — which service owns what, what a good test looks like, what order things merge in — precisely enough that a machine can execute it and a human can review the execution.

Autonomous development isn't an AI capability problem. It's an information architecture problem — and that one you can actually solve.

Why Large Codebases Drain Your AI Token Budget and How to Fit It

Harshit Rathod — Sun, 05 Jul 2026 13:33:09 +0000

A technical breakdown of where context budget goes in large codebases, and the structural patterns that reduce consumption while increasing accuracy.

Hook: You add a new feature to a large NestJS monorepo with Claude's help. By the end of the conversation, the model has read 40 files, re-derived your module conventions twice, and still got the service placement wrong. You spent thousands of tokens. Claude spent most of them guessing. This guide explains why — and what to do about it.

Key Takeaways

Context windows don't scale with codebases. A large repo has more decisions, more conventions, and more ambiguity — all of which drive up token consumption.
The largest token sinks are re-derivation and uncertainty. Claude reads more files when it doesn't know the architecture; it generates more text when it doesn't know the conventions.
CLAUDE.md is the highest-leverage token saver. A 300-line briefing file can replace hundreds of lines of exploratory file reads per session.
Rules save tokens by preventing regeneration. A wrong pattern that gets corrected costs twice — once to generate, once to fix. A prohibition rule prevents it entirely.
Skills load context on demand. Templates and references in skills only enter the context window when invoked, not on every session.

Quick Answer

Large repositories burn through AI tokens because Claude must read files to infer what any experienced team member already knows: which service owns what, what the error-handling pattern is, how responses are shaped, what's been deliberately removed. Every exploratory read, every wrong-service guess, every pattern that violates a convention and gets corrected is wasted context. The fix is to externalize that tribal knowledge into CLAUDE.md (a briefing loaded every session), rules (prohibitions that prevent wrong output), and skills (on-demand workflows with templates). One-time setup; recurs on every feature.

The Problem: Context Budget Is a Finite Resource

Every token Claude reads or writes is budget spent. Context windows are measured in tokens — not files, not lines — and every session starts with the same ceiling. In a small project, that budget is generous. In a large monorepo with several services, dozens of modules, hundreds of DTOs, and cross-cutting conventions, the budget evaporates fast.

There are two places budget goes:

Input tokens — everything Claude reads: your prompt, files it opens, rules and docs it loads, the running conversation history.
Output tokens — everything Claude generates: code, explanations, corrections, re-generations.

Both are expensive. But in a large repo, the input side is where the hemorrhage starts — because Claude reads aggressively to compensate for what it doesn't know.

Where the Tokens Actually Go

1. Exploratory File Reads

When Claude doesn't know where something lives, it goes looking. In a well-indexed codebase, that might mean reading 3–4 files to locate the right module. In a large monorepo with ambiguous service boundaries, it can mean reading 15–20 before it's confident enough to act.

A typical unconfigured session flow for "add a consumer-visible status to a booking package":

Reads services/ directory listing — orientation
Reads operator-service/src/modules/order/ — wrong service, discovers mismatch
Reads api-service/src/modules/order/ — corrects course
Reads order.entity.ts — finds the shape
Reads order.service.ts — finds the pattern
Reads order.repository.ts — finds the query layer
Reads order.controller.ts — finds the response shape
Reads order.dto.ts — finds the DTO convention
Reads transform-response.helper.ts — finds the adapter pattern
Reads 3–4 more files to verify cross-service adapter usage

That's ~10 file reads before writing a single line of output. Each read costs input tokens. In a large NestJS monorepo, files are not small — services, repositories, and controllers routinely exceed 200–400 lines each.

The same task in a configured session: Claude reads CLAUDE.md, knows the service boundary immediately, reads the 3 directly relevant files, and starts generating. The exploratory reads never happen.

2. Convention Re-derivation

Even when Claude lands in the right file, it still needs to infer your team's conventions. Without explicit documentation, it reads examples to reconstruct patterns:

It reads existing controllers to learn how responses are shaped
It reads existing services to find which logger you use
It reads existing guards to understand your permission system
It reads multiple DTOs to infer your validation patterns

This is pattern-matching by example. It works — but it costs tokens for every session, for every engineer, indefinitely. The conventions don't change; the re-derivation does.

Convention re-derivation cost per session (rough estimate for a large NestJS monorepo):

Convention Claude Must Re-Derive	Files Typically Read	Estimated Token Cost
Service ownership (which belongs where)	3–5 entry points	~2,000–4,000
Response shape and interceptor pattern	2–3 controllers	~1,500–3,000
Permission system (guards + decorators)	2–3 guards/controllers	~1,000–2,000
Error handling (constants + exceptions)	2–3 services	~1,000–2,000
Logger usage	1–2 services	~500–1,000
Import style (alias vs relative)	Several files	~300–600
Total per session (estimation)	~13–18 files	~6,300–12,600 tokens

That's before the prompt, before the output, and before any task-specific reads. It's overhead — pure re-derivation of knowledge your team already has.

3. Wrong-Service Placement and Corrections

When a codebase has multiple services with overlapping domains — say, a package entity that exists in both the operator service (definition) and the consumer API (consumer-visible metadata) — Claude will guess. Sometimes it guesses right. Often it doesn't.

A wrong-service guess costs tokens in three ways:

Exploration in the wrong service — reading module structure, entities, and services in a service that won't receive the change
Generating the wrong output — producing code in the wrong service
Correction — you point out the error; Claude re-reads, re-reasons, and regenerates

In practice, one wrong-service guess can cost more tokens than the correct implementation from the start.

4. Pattern Violations and Regeneration

Without explicit prohibitions, Claude uses its training defaults. Those defaults are reasonable — but they won't match your team's conventions. Common mismatches in NestJS projects:

console.log instead of a structured logger
if (user.roles.includes('admin')) instead of PermissionCodes
Relative ../../ imports instead of the src/ alias
Hardcoded error strings instead of ErrorMessages constants
Raw DB queries in a service instead of going through a repository

Each violation costs tokens twice: once to generate the wrong pattern, once to correct it. A single code generation that needs three corrections has effectively quadrupled the output token cost for that block.

5. Conversation History Accumulation

As a session grows, the running conversation history is included in every subsequent call. In a long debugging or implementation session:

Early file reads stay in context even when they're no longer relevant
Corrections and re-generations add to history
Claude's reasoning about dead ends accumulates

A session that spans 20 exchanges in a large codebase can have a conversation history that alone approaches the token limit of shorter sessions.

The Fix: Externalize Knowledge, Don't Re-Derive It

The underlying cause of excess token consumption is the same in every case: Claude is spending tokens to learn things your team already knows. The fix is to make that knowledge available upfront, in a form Claude can read efficiently, rather than re-deriving it from source files every session.

Three mechanisms do this, each suited to a different type of knowledge:

Mechanism	What it encodes	When Claude reads it	Token impact
`CLAUDE.md`	Architecture, ownership, conventions	Loaded automatically, every session	Replaces exploratory reads
Rules	Hard prohibitions and invariants	Always active; prevents wrong output	Eliminates regeneration cost
Skills	Multi-step workflows + templates	On demand, when invoked	Keeps templates out of always-on context

CLAUDE.md: Replace Exploration With Declaration

CLAUDE.md is the single highest-leverage tool for reducing token consumption. It's loaded at the start of every session, before any file reads, and it replaces the exploratory phase entirely for the information it contains.

The key insight is specificity over completeness. A bloated CLAUDE.md that describes everything about NestJS is worse than a lean one that answers the exact questions Claude would otherwise need to read files to answer:

Which service owns what kind of data?
What does the standard response shape look like?
How does cross-service communication work?
What are the project-specific patterns (logger, errors, permissions)?

A 300-line CLAUDE.md that precisely answers those questions saves more tokens than a 1,000-line one that also explains what a repository pattern is.

What to Include

Service Routing Decision Table

This is the single most effective thing you can document. Instead of Claude reading 10 files to figure out which service owns a new feature, it reads one table:

Which Service Owns What

- operator-service — if the data describes _what an experience is_:
  package definitions, pricing, taxes, availability, operator accounts.
- api-service — if the data describes _a consumer's interaction_:
  bookings, users, auth, trip planning, payments, notifications.

| Task involves...                   | Service                            |
| ---------------------------------- | ---------------------------------- |
| Package categories, pricing, slots | operator-service                   |
| Booking status, user profiles      | api-service                        |
| Stripe payments (consumer side)    | api-service                        |
| Cross-service booking flow         | Start in api-service → IMS adapter |

This table costs ~150 tokens to include in the context. It replaces 2,000–4,000 tokens of exploratory service reads. That's a 10–25× return on every session.

Conventions That Would Otherwise Be Re-Derived

Document only what isn't already obvious from reading a single file:

## What Claude Must Not Do

- `console.log` → use `logMessage()` from `src/common/utils/logger`
- Check `user.role` → use `PermissionCodes` + `@Permissions()`
- DB call inside a loop → use bulk queries (`IN`, `JOIN`)
- Relative `../../` imports → use the `src/` alias
- TypeORM `synchronize: true` → Flyway manages all schema changes

Five prohibitions. ~100 tokens. Replaces all the file reads Claude would do to infer these patterns — and eliminates the regeneration cost when it gets them wrong.

Response Shape

Include the exact shape, not a prose description:

## Standard Response Shape

Controllers return `{ data, meta }`. TransformInterceptor wraps automatically:

return { data: { items }, meta: { path: request.path } };
// → { success: true, data: { items }, meta: { path }, error: null }

Without this, Claude reads 2–3 controllers to infer the pattern. With it, Claude knows immediately — and gets it right the first time.

What to Exclude

The token efficiency of CLAUDE.md depends as much on what you leave out as what you put in:

Framework documentation — Claude already knows what a NestJS guard is. Document only your project-specific guard setup.
Code that's derivable from files — if Claude can read one file and learn a pattern, don't repeat it in CLAUDE.md.
Stable, obvious conventions — use TypeScript, use async/await, follow the module pattern. These are defaults; they cost tokens but add no information.
Task-specific templates — templates belong in skills, not CLAUDE.md. They should enter the context on demand, not every session.

Target: under 300 lines. If your CLAUDE.md is longer, audit it for derivable content. Every line that doesn't prevent a file read or a wrong pattern is a line that should be cut.

Rules: Prevent Regeneration at the Source

A wrong pattern that's regenerated after correction costs twice the tokens of getting it right the first time. Rules cut this cost to zero by making the wrong pattern impossible to generate.

Rules live in .claude/rules/ as Markdown files. They're phrased as prohibitions — not preferences — because "NEVER call the DB in a loop" is enforced, while "prefer bulk queries" is suggestion that gets ignored under pressure.

Token Cost of a Rule vs. a Correction

Consider N+1 queries. Without a rule, here's what happens:

Claude generates code with a DB call inside a loop (output tokens)
You read the generated code and identify the N+1 (your time)
You explain the issue to Claude (input tokens)
Claude re-reads the context to understand the correction (context re-processing)
Claude regenerates the correct bulk-query version (output tokens)

Total: roughly 2× the output tokens for that block, plus the input tokens for the correction exchange.

With a rule:

Rule is in context; Claude generates the correct bulk-query pattern (output tokens)

Total: 1× output tokens.

The rule itself costs ~200 tokens to include in the session. It saves 1× output tokens plus correction overhead on every N+1 occurrence. In a session with 3–4 such violations, it pays for itself many times over.

High-Value Rules for NestJS Projects

Rules that deliver the highest token savings are those that prevent patterns Claude's training considers reasonable but that violate your project's conventions:

N+1 Query Prevention — Claude defaults to per-entity lookups in loops; this stops it:

# Database Query Rules — No N+1

NEVER make a database call inside a loop. Use a single bulk query, then
group results in memory. If unsure whether a pattern causes N+1, ask first.

Permission System — Claude defaults to role-name checks; this redirects it:

# Authorization — Never Check Role Names

NEVER check `user.role`, `user.roles`, or any role-name string.
Use `@Permissions([PermissionCodes.X])` with `PermissionsGuard` instead.

Import Style — Claude defaults to relative imports; this enforces the alias:

# Imports — Always Use the Path Alias

NEVER use relative imports that traverse more than one directory level.
Use `src/modules/...` alias imports everywhere.

Each of these rules costs ~100–200 tokens per session to include. Each saves the token cost of generating a violation plus the correction exchange — conservatively 500–2,000 tokens per occurrence.

Skills: Keep Templates Out of Always-On Context

Skills are on-demand context. Templates, references, and workflow guides for repeated tasks are exactly the kind of high-token content that should not be in CLAUDE.md — because they're only relevant when you're doing that specific task.

A controller template for your NestJS service is ~50–100 lines. In a CLAUDE.md, that's 50–100 lines of context included in every session, even when you're debugging, writing tests, or reading logs. In a skill, those same lines only enter the context when you run /api-development.

Token Budget Impact of Skills

Content	In CLAUDE.md (always loaded)	In a skill (on demand)
Controller template (80 lines)	~400 tokens × every session	~400 tokens × only when invoked
Service template (80 lines)	~400 tokens × every session	~400 tokens × only when invoked
Repository template (60 lines)	~300 tokens × every session	~300 tokens × only when invoked
DTO examples (40 lines)	~200 tokens × every session	~200 tokens × only when invoked
Total	~1,300 tokens per session	~1,300 tokens when you need it

If you scaffold endpoints 3 times a week but run 20 sessions per week, templates in CLAUDE.md cost 20 × 1,300 = 26,000 tokens. In a skill, they cost 3 × 1,300 = 3,900 tokens. Same result, 85% fewer tokens for the templates alone.

Skill Structure

.claude/skills/api-development/
├── SKILL.md                    # Workflow: trigger, steps, decision points
├── assets/
│   ├── controller-template.md  # Real, compilable code templates
│   ├── service-template.md
│   ├── repository-template.md
│   └── dto-template.md
└── references/
    ├── nestjs-conventions.md
    └── swagger-documentation.md

The SKILL.md workflow guides Claude through the task deterministically — DTO first (it defines the contract), then repository (queries only), then service (business logic), then controller (HTTP routing). Without the workflow, Claude invents its own order and sometimes generates the controller before the DTO exists, requiring re-generation.

Architecture: Per-Service CLAUDE.md Files

A monorepo has a root context problem. Everything in the root CLAUDE.md loads every session, regardless of which service you're working in. Details specific to operator-service's DI patterns are wasted tokens when you're debugging auth in api-service.

The fix is a two-level structure:

.claude/CLAUDE.md                   # Cross-cutting: routing, shared conventions
services/
  api-service/CLAUDE.md             # api-service specific: module patterns, auth, DI
  operator-service/CLAUDE.md        # operator-service specific: IMS adapter, pricing

Claude reads the root CLAUDE.md always, and the service-level file when you work in that directory. Cross-cutting concerns (service ownership, response shape, shared error constants) live at root. Service-specific depth (auth flows, module patterns, DI tokens) lives in the service.

Token impact: If each service file is 150 lines (~750 tokens), keeping them separate means you load at most 750 extra tokens per session instead of both services' details at all times. For a multi-service monorepo, that's up to 2,250 tokens of context avoided per session.

Measuring the Impact

Here's the before/after for a realistic "add a consumer-visible booking status" task in a large NestJS monorepo:

Without Configuration

Phase	Token Estimate
Exploratory directory reads (service placement)	~3,000
Convention re-derivation (logger, perms, errors)	~6,000
Wrong-service generation and correction	~4,000
Pattern violations and regeneration (3×)	~3,000
Actual task output (correct code, 4 files)	~4,000
Total	~20,000

With CLAUDE.md + Rules + Skills

Phase	Token Estimate
CLAUDE.md load (routing, conventions, shape)	~1,500
Rules load (3 rules)	~600
Targeted file reads (3 directly relevant files)	~2,500
Skill invocation (templates, workflow)	~1,300
Actual task output (correct code, 4 files)	~4,000
Total	~9,900

~50% reduction in total token consumption for a single task. For a team running dozens of sessions per week, the savings are substantial — and they compound because the ratio stays roughly constant across tasks.

Common Mistakes That Maximize Token Waste

Each of these looks harmless and silently burns budget across every session.

Putting templates in CLAUDE.md. Templates are task-specific. Loading them every session is waste. Move them to skills.
Writing CLAUDE.md as a tutorial. Explaining NestJS fundamentals Claude already knows inflates context without replacing any file reads. Document only what's unique to your project.
Omitting the routing decision table. Service placement ambiguity is the single largest driver of exploratory reads. A table makes the decision free.
Writing rules as preferences. "Prefer bulk queries" leaves Claude room to choose. "NEVER call the DB in a loop" doesn't. The second form prevents regeneration; the first doesn't.
One flat CLAUDE.md for a monorepo. All service-specific content loads every session. Split into root + per-service files.
No cross-service communication rules. Without explicit guidance, Claude reaches across service boundaries — reads the wrong DB, imports across services. The correction exchange is expensive. One sentence in CLAUDE.md prevents it.

Real-World Example: Token Budget on a Feature Request

The request: "Add a consumer-visible status to a booking package."

Unconfigured session token trace:

[read] services/                              ~200 tokens
[read] operator-service/src/modules/order/ ~150 tokens
[read] operator-service order.entity.ts    ~600 tokens  ← wrong service
[read] api-service/src/modules/order/      ~150 tokens  ← course correction
[read] api-service order.entity.ts         ~500 tokens
[read] api-service order.service.ts        ~800 tokens
[read] api-service order.repository.ts     ~600 tokens
[read] api-service order.controller.ts     ~700 tokens
[read] api-service order.dto.ts            ~400 tokens
[read] transform-response.helper.ts          ~300 tokens
[read] ims-adapter.ts                        ~700 tokens
...                                          ~3,000 more (permissions, logger, errors)
[generate] wrong permission check            ~400 tokens
[correction] permission explanation          ~200 tokens
[generate] correct permission                ~200 tokens
[generate] actual implementation (4 files)  ~4,000 tokens
Total: ~12,900 input + ~4,600 output ≈ 17,500 tokens

Configured session token trace:

[load] CLAUDE.md (routing, conventions)      ~1,500 tokens
[load] rules (3 rules)                        ~600 tokens
[invoke] /api-development skill             ~1,300 tokens
[read] api-service order.service.ts        ~800 tokens  ← targeted read
[read] api-service order.repository.ts     ~600 tokens  ← targeted read
[read] ims-adapter.ts                        ~700 tokens  ← targeted read
[generate] implementation (4 files, correct) ~4,000 tokens
Total: ~5,500 input + ~4,000 output ≈ 9,500 tokens

The implementation output is nearly identical. The savings come entirely from eliminating exploratory reads, wrong-service generation, and pattern violations.

Summary: The Token Budget Formula

Token consumption in a large repo follows a predictable formula:

Total tokens = (exploration overhead) + (re-derivation overhead) + (correction overhead) + (actual task output)

Configuration attacks the first three terms:

CLAUDE.md eliminates exploration overhead and most re-derivation overhead
Rules eliminate correction overhead
Skills shift task-specific re-derivation from every-session to on-demand

The actual task output — the code you asked for — is roughly constant. Everything else is overhead, and it's reducible.

FAQ

Why does Claude read so many files in a large repo?
Claude compensates for uncertainty with exploration. When it doesn't know which service owns a feature, it reads multiple services to decide. When it doesn't know your response shape, it reads multiple controllers. CLAUDE.md replaces that uncertainty with declared knowledge, eliminating the reads.

Does a larger CLAUDE.md always save more tokens?
No — the relationship inverts past a threshold. A 300-line CLAUDE.md that answers the right questions saves more tokens than a 1,000-line one that also includes tutorials and templates. The goal is maximum information density per line, not maximum coverage.

How much do wrong patterns actually cost?
A single N+1 query correction in a longer session can cost 500–2,000 tokens: input for your correction message plus output for the re-generation. Across a week of development with multiple sessions, prevention rules pay for themselves quickly.

Can I measure token usage per session in Claude Code?
Claude Code doesn't currently expose per-session token metrics directly. Proxy signals: session length before context compression kicks in, whether you see "context window approaching limit" warnings, and how many file reads appear in the tool call log.

Are skills just macros?
Skills are more than macros — they bundle a workflow (ordered steps, decision points), templates (compilable code), and references (conventions, Swagger patterns) into a single invocable command. The workflow is what prevents out-of-order generation and the correction overhead that comes with it.

Should CLAUDE.md be the same for every engineer on the team?
Yes — commit it to git so the configuration is shared and versioned. Personal overrides go in .claude/settings.local.json, which is gitignored. The team-level conventions in CLAUDE.md apply to everyone.

Does this approach work for repos that aren't NestJS?
The token-saving logic applies to any large codebase with team-specific conventions. The specific content changes (replace NestJS patterns with your stack's patterns), but the structure — CLAUDE.md for routing and conventions, rules for prohibitions, skills for repeated workflows — is framework-agnostic.

Key Takeaways (Recap)

Token waste in large repos has a root cause: Claude reads files to learn what your team already knows. The fix is to tell it upfront.
CLAUDE.md replaces exploration. A service routing table costs ~150 tokens; it replaces 2,000–4,000 tokens of exploratory reads per session.
Rules eliminate regeneration. A prohibition costs ~200 tokens once; it saves 500–2,000 tokens every time the wrong pattern would have been generated.
Skills keep templates off the always-on context. Load them only when you're scaffolding, not in every session.
Split by service. Per-service CLAUDE.md files prevent service-specific context from loading in unrelated sessions.
The savings compound. Every session, every engineer, every feature — the overhead reduction is consistent because the root cause is structural.

Conclusion

Token exhaustion in large repositories isn't a limitation of the AI — it's an information architecture problem. Claude reads aggressively because the knowledge it needs to act confidently isn't in any single file. It re-derives conventions that haven't changed. It generates wrong patterns that get corrected. It explores the wrong service before finding the right one.

The fix isn't a larger context window. It's externalizing your team's tribal knowledge into structured, version-controlled form — a CLAUDE.md that answers the questions Claude would otherwise spend tokens asking, rules that prevent the patterns it would otherwise spend tokens regenerating, and skills that load task-specific context only when you need it.

The investment is a few hours. The savings recur on every session, for every engineer, indefinitely.

Claude Code for NestJS Monorepos: A Practical Setup Guide

Harshit Rathod — Sun, 07 Jun 2026 08:53:54 +0000

A practical, step-by-step guide to configuring Claude Code with CLAUDE.md, rules, and skills so AI-generated code matches your team's conventions in a large NestJS monorepo.

Hook: Ask Claude to "add a consumer-visible status to a booking" in an unconfigured monorepo, and it will happily edit the wrong microservice, hardcode an error string, and check user.role === 'admin'. None of that is Claude being wrong — it's Claude guessing. This guide removes the guessing.

Key Takeaways

Claude Code reads .claude/ from your git root, so one configuration governs every service in the monorepo.
Three mechanisms do the heavy lifting: CLAUDE.md (always-loaded project briefing), rules (hard prohibitions), and skills (multi-step workflows with templates).
The single biggest win is service routing — a decision table in CLAUDE.md stops Claude from putting consumer logic in the operator service.
Write rules as prohibitions, not preferences — "NEVER query the DB in a loop" is enforced; "prefer bulk queries" is ignored under pressure.
Setup is a few hours, one-time, and pays back on every feature: faster scaffolding, fewer convention violations in review, and faster onboarding.

Quick Answer

To set up Claude Code for a NestJS monorepo:
(1) install it with npm install -g @anthropic-ai/claude-code and authenticate once via claude; (2) create a root .claude/CLAUDE.md that documents which service owns what, your request pipeline, and your standard response shape; (3) add a .claude/rules/ folder with hard prohibitions (no N+1 queries, no role-name checks, no relative imports); (4) build a .claude/skills/ folder with multi-step workflows and code templates for repeated tasks like creating an endpoint; and (5) add .claude/settings.json to allow safe commands and deny destructive ones. Commit .claude/ to git so the whole team shares it. The result: Claude generates code that follows your conventions on the first try, instead of guessing.

The Problem: Why Claude Struggles With Large NestJS Projects

A large NestJS monorepo is one of the hardest environments for any AI coding assistant, because correctness depends on conventions that are invisible in any single file. A codebase with dozens of modules, hundreds of DTOs, and custom guards, interceptors, filters, and adapters is genuinely ambiguous. Without context, Claude fills that ambiguity with reasonable defaults — and those defaults won't match your team's conventions.

Concretely, an unconfigured Claude will:

Call the database directly from a service instead of going through a repository
Hardcode error strings instead of using your ErrorMessages constants
Put a new file in the wrong service (booking logic in operator-service when it belongs in api-service)
Check user.role === 'admin' instead of using PermissionCodes
Use console.log instead of your structured logger
Write ../../common/utils instead of the src/ path alias

Why This Problem Exists

These aren't bugs in Claude — they're the predictable result of asking a model to infer team-specific decisions it was never told about. An AI assistant only sees the files it reads in a session; it cannot see why your team removed RolesGuard, that synchronize must stay false, or that two services communicate only over HTTP adapters. Tribal knowledge that lives in your engineers' heads is exactly the knowledge Claude lacks.

The fix is to externalize that tribal knowledge into version-controlled context through three mechanisms, each suited to a different kind of knowledge:

Mechanism	What it encodes	When Claude uses it
`CLAUDE.md`	Architecture, ownership, conventions	Loaded automatically every session
Rules	Hard prohibitions and invariants	Enforced on every code generation
Skills	Multi-step workflows + templates	Invoked on demand for repeated tasks

Repository Structure

Before configuring anything, anchor on the layout. A well-structured NestJS monorepo looks like this:

my-backend/
├── .claude/                  # Everything Claude needs to operate well
│   ├── CLAUDE.md             # Root-level instructions (always loaded)
│   ├── rules/                # Enforced coding constraints
│   ├── skills/               # Custom slash commands with deep context
│   └── settings.json         # Command permissions
├── services/
│   ├── api-service/          # NestJS consumer API (port 5001)
│   ├── operator-service/     # NestJS operator/vendor API (port 5002)
│   ├── chat-service/         # Express + Socket.IO (JavaScript, port 5005)
│   └── job-service/          # Scheduled jobs, no HTTP server
├── db/migration/             # Flyway migrations per schema
└── package.json              # Root: only husky + lint-staged

Each service is an independent NestJS app with its own package.json, tsconfig.json, and build output. Inside each service, every feature module follows the same strict three-layer structure:

src/modules/booking/
├── booking.module.ts
├── controllers/    # HTTP routing only, no logic
├── services/       # Business logic and orchestration
├── repositories/   # TypeORM queries only
└── dtos/           # Request/response shapes, validation

Why it matters: This separation is exactly what Claude needs to respect. If it doesn't know the pattern, it mixes layers — services querying the DB directly, controllers calling repositories.

Suggested visual: a diagram of the git-root .claude/ directory applying across all four services.

Step-by-Step: Configuring Claude Code for NestJS

Step 1 — Install Claude Code

npm install -g @anthropic-ai/claude-code
claude   # opens a browser for one-time OAuth

After authenticating, claude works from any directory. Each developer installs and authenticates independently — there's no shared API key.

Monorepo tip: Claude reads .claude/ from the git root, so its instructions apply no matter where you invoke Claude. When working on one service, cd into it (e.g. services/api-service/) so file searches and commands scope correctly.

Step 2 — Create CLAUDE.md

CLAUDE.md is the single most important file you will write — it's the briefing Claude reads at the start of every session. Think of it as onboarding documentation for a senior engineer on day one. Place it at two levels:

Root .claude/CLAUDE.md — service ownership, shared conventions, the request pipeline
Per-service services/{service}/CLAUDE.md — module patterns, auth, and DI specific to that service

The Root CLAUDE.md

Problem: Claude can't tell which service should own a new file, so it guesses — and lands consumer logic in the operator service.
Solution: A routing decision table plus explicit "never do this" rules.
Result: Files land in the correct service on the first pass.

# CLAUDE.md

## Monorepo Structure

Four services under `services/`, each independently runnable.
Run all commands from inside the service directory.

| Service            | Port | Stack                    | Purpose              |
| ------------------ | ---- | ------------------------ | -------------------- |
| `api-service`      | 5001 | NestJS + TypeScript      | Consumer-facing API  |
| `operator-service` | 5002 | NestJS + TypeScript      | Operator/vendor mgmt |
| `chat-service`     | 5005 | Express + Socket.IO + JS | Real-time messaging  |
| `job-service`      | —    | Node.js + TypeScript     | Scheduled jobs       |

## Which Service Owns What

- **operator-service** — if the data describes _what an experience is_:
  package definitions, pricing, taxes, availability, operator accounts.
- **api-service** — if the data describes _a consumer's interaction_:
  bookings, users, auth, trip planning, payments, notifications.

| Task involves...                   | Service                            |
| ---------------------------------- | ---------------------------------- |
| Package categories, pricing, slots | operator-service                   |
| Booking status, user profiles      | api-service                        |
| Stripe payments (consumer side)    | api-service                        |
| Cross-service booking flow         | Start in api-service → IMS adapter |

## Global Request Pipeline (in order)

1. `TraceContextMiddleware` — sets `correlationId` in `AsyncLocalStorage`
2. `ValidationPipe` — whitelist mode, flattens DTO errors
3. `LoggerInterceptor` — logs request/response
4. `TransformInterceptor` — wraps return value in the standard shape
5. Exception filters (`HttpExceptionFilter`, `TypeOrmExceptionFilter`, …)

## Standard Response Shape

Controllers return `{ data, meta }`; `TransformInterceptor` wraps it:
return { data: { items }, meta: { path: request.path } };
// → { success: true, data: { items }, meta: { path }, error: null }

## Cross-Service Communication

api-service NEVER touches operator-service's database. All reads/writes go
through HTTP adapters in `src/common/adapters/` (they handle OAuth refresh and
trace propagation). Need operator data? Call the adapter, never the DB.

## What Claude Must Never Do

- Use `console.log` → use `logMessage()` from `src/common/utils/logger`
- Check `user.role` → use `PermissionCodes` + `@Permissions()`
- Query the DB inside a loop → use bulk queries (`IN`, `JOIN`)
- Use relative `../../` imports → use the `src/` alias
- Set TypeORM `synchronize: true` → Flyway manages all schema changes

What makes a good CLAUDE.md:

Decision rules over directory listings. "If the data describes what an experience is, it lives in operator-service" lets Claude resolve ambiguity without asking you.
Include the response shape. Otherwise Claude manually wraps responses in every controller, creating inconsistencies.
List what NOT to do. "Never use console.log" is more actionable than "use our logger."
Document what was removed. When you delete a RolesGuard or a synchronize flag, say why — or Claude will reintroduce it because it looks natural.

Service-Level CLAUDE.md

Each service gets its own file for details too specific for the root:

# api-service/CLAUDE.md

## Module Architecture — never mix layers

controllers/ HTTP routing only — call service, return data
services/ Business logic — orchestrate repos, no direct DB calls
repositories/ TypeORM queries only — accept EntityManager for transactions

## Authentication

- `JwtAuthGuard` validates Bearer tokens, attaches `UserRequest`
- `PermissionsGuard` reads `@Permissions([PermissionCodes.X])`
- Never use RolesGuard or check role names — removed intentionally

## Dependency Injection

Register services by interface token, and inject by token, not class:
{ provide: SERVICE_INTERFACE.BOOKING_SERVICE, useClass: BookingService }

## Background Jobs

BullMQ + Redis. Processors live in `src/modules/{module}/processors/`.
Enqueue via the module's service — never from a controller.

Step 3 — Add Rules

Rules are hard prohibitions — they don't describe architecture, they prevent specific patterns, like an ESLint config for AI-generated code. They live in .claude/rules/ as Markdown files.

Use `CLAUDE.md` for	Use `rules/` for
Architecture, module structure	Hard prohibitions
Service ownership decisions	Patterns Claude must never emit
Conventions, command reference	Security / performance invariants

Rule: Prevent N+1 Queries

Problem: N+1 queries are easy to introduce and slip through review.
Solution: a prohibition rule with a correct bulk-query pattern.
Result: Claude writes the bulk query at generation time — the bug is never created.

.claude/rules/database-queries.md

// Wrong — N queries
for (const b of bookings) {
  b.user = await this.userRepo.findOne(b.userId);
}

// Correct — one query
const users = await this.userRepo.find({ where: { id: In(userIds) } });
const userMap = new Map(users.map((u) => [u.id, u]));
bookings.forEach((b) => {
  b.user = userMap.get(b.userId);
});

Rule: Permission Checks

.claude/rules/permissions.md

// Wrong
if (user.roles.includes('admin')) { ... }

// Correct
@Permissions([PermissionCodes.MANAGE_BOOKINGS])
@UseGuards(JwtAuthGuard, PermissionsGuard)

Why: role names get merged, split, and renamed; checks against them break
silently. PermissionCodes are stable constants that survive role
restructuring. Import from src/common/constants/permissions.constant.ts.

Rule: Import Style

.claude/rules/imports.md

// Wrong
import { UserService } from "../../services/user.service";
// Correct
import { UserService } from "src/modules/user/services/user.service";

The src/ alias is configured in tsconfig.json (baseUrl: "./") and Jest's
moduleNameMapper. Use it everywhere.

Other Rules Worth Defining

The same prohibition pattern applies to many recurring NestJS pitfalls. A few more rules worth their own file:

Error handling — always throw from ErrorMessages/ResponseCodeKeys constants and use NestJS exceptions; never hardcode strings or return raw error objects.
Logging — use the structured logMessage() helper at the right level; never console.log.
Transactions — multi-write operations must run in a single EntityManager transaction; never fire independent writes that can half-commit.
DTO validation — every request DTO needs class-validator decorators; the ValidationPipe whitelist drops anything undecorated, so missing decorators silently lose data.
Entity ↔ migration parity — any entity change needs a matching Flyway migration; synchronize stays false.
Swagger coverage — every endpoint carries @ApiSpec + a typed response DTO so the generated docs stay accurate.

Step 4 — Build Skills

Skills are project-specific slash commands that bundle a workflow, code templates, and references — they turn a repeated multi-file task into one command. Write one for any repeated, multi-step task: building an endpoint, writing a migration, scaffolding a module, reviewing a PR.

Skill Structure

.claude/skills/api-development/
├── SKILL.md                    # Workflow, trigger, steps
├── assets/
│   ├── controller-template.md
│   ├── service-template.md
│   ├── repository-template.md
│   └── dto-template.md
└── references/
    ├── nestjs-conventions.md
    └── swagger-documentation.md

Writing SKILL.md

# API Development Skill

## Trigger

Invoke with `/api-development` when building or modifying a NestJS endpoint.

## Workflow

1. **Determine service & module** — check CLAUDE.md routing; ask if ambiguous.
2. **Read what exists** — entities, repositories, DTOs already in the module.
3. **Generate the DTO first** — it defines the contract. class-validator
   decorators; extend `PaginationRequestDTO` for lists.
4. **Generate the repository** — inject `DataSource`; accept an optional
   `EntityManager` for transactions; queries only, no logic.
5. **Generate the service** — inject the repository interface token; use
   `ErrorMessages` constants; throw `NotFoundException` etc.
6. **Generate the controller** — `@ApiSpec` + `@ApiOkResponse`; return
   `{ data, meta }`; no business logic.
7. **Wire the module** — add to `providers`, export by interface token.

Asset Template (example)

Templates should be real, compilable code — not pseudocode. assets/controller-template.md:

@ApiTags("bookings")
@Controller("bookings")
export class BookingController {
  constructor(
    @Inject(SERVICE_INTERFACE.BOOKING_SERVICE)
    private readonly bookingService: IBookingService,
  ) {}

  @Post()
  @UseGuards(JwtAuthGuard, PermissionsGuard)
  @Permissions([PermissionCodes.CREATE_BOOKING])
  @ApiSpec({ summary: "Create a new booking" })
  @ApiCreatedResponse({ type: CreateBookingSuccessDto })
  async createBooking(
    @Body() dto: CreateBookingDto,
    @Req() req: UserRequest,
  ): Promise<{ data: BookingEntity }> {
    const booking = await this.bookingService.createBooking(dto, req.user.id);
    return { data: booking };
  }
}

With this skill, a complete endpoint (controller + service + repository + DTOs, wired into the module) takes under 3 minutes instead of ~20 — and matches your conventions on the first try.

Other Skills Worth Building

Any repeated, multi-step workflow with team-specific conventions is a skill candidate. Beyond endpoint scaffolding:

Migration generator — scaffold a Flyway migration in the right schema folder with your versioning and naming convention, plus the matching entity change.
Module scaffolder — generate a full module skeleton (module file, three layers, DI tokens) wired and ready.
PR review — review a diff against your conventions: N+1 checks, permission usage, layer boundaries, missing tests.
Test generator — produce *.spec.ts files following your mocking and fixture patterns for a given service.
Cross-service adapter — generate a new IMS adapter method plus its response interface and transform helper.
Use-case / BDD docs — turn a requirement into user stories with Given/When/Then acceptance criteria.

Step 5 — Configure Settings & Permissions

.claude/settings.json controls which Bash commands run without a permission prompt. Allow read-only and safe test/lint operations freely; deny anything destructive.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(npx jest *)"
    ],
    "deny": ["Bash(rm -rf *)", "Bash(git push *)", "Bash(git reset --hard *)"]
  }
}

File	Applies to	Committed
`.claude/settings.json`	Everyone on the team	Yes
`.claude/settings.local.json`	You only (overrides)	No (gitignored)

Best Practices

Best Practice callout: Treat .claude/ as production code. It ships your conventions to every engineer and every AI session — review it, version it, and prune it like any other source.

Keep CLAUDE.md under ~300 lines. Context has a cost; a bloated file crowds out the code Claude needs to read. If it's derivable from the code, cut it.
Write rules as prohibitions, not guidance. "NEVER call the DB in a loop" is enforced; "prefer bulk queries" is ignored under pressure.
Put templates in skills, not CLAUDE.md — they should load only when the skill is invoked, not on every session.
Version .claude/ in git. It's part of your codebase: same review, same history. New rules get PRs; stale rules get deleted.
Use decision tables liberally. Anywhere two reasonable choices exist — DTO placement, entity location, service boundaries — a table beats prose.

Recommended `.claude/` layout

.claude/
├── CLAUDE.md                  # Root guide (<300 lines)
├── settings.json              # Team permissions (committed)
├── rules/
│   ├── database-queries.md    # No N+1
│   ├── permissions.md         # PermissionCodes, no role checks
│   └── imports.md             # src/ alias only
└── skills/
    └── api-development/
        ├── SKILL.md
        ├── assets/            # controller/service/repository/dto templates
        └── references/        # conventions, swagger

Common Mistakes

⚠️ Each of these silently degrades output quality — Claude will look like it's working while quietly violating your conventions.

Writing CLAUDE.md as a tutorial. Don't explain what NestJS is — Claude knows. Document only what's unique to your project: module names, error constants, response shape, permission system.
Omitting negative rules. Telling Claude what not to do prevents whole classes of mistakes. The expensive errors are the ones that look correct but violate your patterns.
Cramming everything into the root CLAUDE.md. It loads in every session. Split service-specific depth into per-service files so it doesn't pollute context when you're elsewhere.
No routing decision table. Wrong-service placement comes from ambiguity, not ignorance. A table makes the decision deterministic.
Forgetting the cross-service adapter pattern. In an HTTP-linked monorepo, Claude will try to import across services or query the other DB. Spell out that all cross-service calls go through adapters.
Not mentioning synchronize: false. Claude assumes TypeORM manages the schema. If you use Flyway, entity changes without a matching migration fail silently — say so explicitly.

Real-World Example: Adding a Consumer-Visible Booking Status

A walkthrough of how a configured setup changes one real task.

The request: "Add a consumer-visible status to a booking package."

Without configuration, Claude reasons: "packages live in operator-service," and edits the package entity there — the wrong service. It hardcodes the status string, and adds an if (user.roles.includes('admin')) guard.

With configuration, here's the chain:

Routing table in CLAUDE.md tells Claude that consumer-visible status describes a consumer interaction → it belongs in api-service, not operator-service.
Cross-service rule reminds it the operator's package definition is read via an IMS adapter, so it adds the field to the adapter's transform — not by reaching into the other DB.
/api-development skill scaffolds the DTO, repository method, service logic, and controller in the right order.
Permission rule makes it emit @Permissions([PermissionCodes.VIEW_BOOKING_STATUS]) instead of a role check.
Error rule makes it throw NotFoundException with an ErrorMessages constant.

One ambiguous sentence, resolved into correct, convention-matching code across four files — without a single clarifying question.

Results & Metrics

A few hours of one-time setup changes the day-to-day in measurable ways:

Before	After
Review every generated file for hardcoded strings, wrong imports, role checks	Rules make those impossible — review focuses on logic, not conventions
New endpoint ≈ 20 min wiring four layers by hand	`/api-development` scaffolds + wires it in under 3 min
Files landed in the wrong service, caught late in review	Routing table places them correctly on the first pass
N+1 queries and `console.log` slipped into PRs	Caught at generation time, never written
New hires guessed at module boundaries and patterns	CLAUDE.md teaches the conventions implicitly on day one

Compounding wins that don't show up in a single PR:

Consistency. Code generated months apart looks the same, because it comes from the same templates and rules — not from whatever Claude inferred that day.
Less review fatigue. Reviewers stop flagging the same convention violations and spend attention on actual design.
Faster onboarding. Routing tables and rules are documentation that also executes — a new engineer's first AI-assisted feature already follows house style.
Lower context cost. A tight CLAUDE.md plus on-demand skills means Claude spends its context budget reading your code, not re-deriving conventions every session.

Extractable insight: The investment pays for itself within the first few features and keeps paying on every one after — because the cost is one-time and the benefit recurs on every task.

FAQ

What is CLAUDE.md?
CLAUDE.md is a Markdown file Claude Code reads automatically at the start of every session. It briefs the AI on your project's architecture, conventions, and prohibitions — the equivalent of onboarding docs for a new engineer.

Where should CLAUDE.md go in a monorepo?
Put a root .claude/CLAUDE.md at the git root for cross-cutting concerns (service ownership, shared conventions), and a CLAUDE.md inside each service for service-specific patterns. Claude reads the root first, then the service-level file when you work in that directory.

What's the difference between CLAUDE.md and rules?
CLAUDE.md describes architecture and conventions; rules (in .claude/rules/) are hard prohibitions Claude must never violate. Use CLAUDE.md for "here's how things work" and rules for "never do this," such as banning N+1 queries or role-name checks.

How do Claude Code skills work?
A skill is a project-specific slash command (e.g. /api-development) backed by a SKILL.md workflow plus code templates and references. Invoking it makes Claude follow a deterministic, multi-step process — like scaffolding a full NestJS endpoint across four files.

How long should CLAUDE.md be?
Aim for under ~300 lines. Context is finite, and a bloated file crowds out the actual code Claude needs to read. Document only what isn't derivable from the codebase itself.

Does Claude Code work with a NestJS monorepo of multiple services?
Yes. Claude reads .claude/ from the git root, so one configuration governs every service. A routing decision table in CLAUDE.md tells Claude which service owns which kind of data.

How do I stop Claude from writing N+1 queries or role-based permission checks?
Add prohibition rules in .claude/rules/. A database-queries.md rule bans DB calls inside loops; a permissions.md rule bans user.role checks in favor of PermissionCodes and @Permissions().

Should I commit the .claude directory to git?
Yes — commit .claude/CLAUDE.md, rules/, skills/, and settings.json so the whole team shares the same configuration. Keep personal overrides in .claude/settings.local.json, which is gitignored.

Key Takeaways (Recap)

Claude struggles in large NestJS monorepos because correctness depends on conventions invisible in any single file.
Externalize that knowledge with CLAUDE.md (briefing), rules (prohibitions), and skills (workflows) — all committed to git.
The service-routing decision table is the highest-leverage thing you can write.
Rules phrased as prohibitions are enforced; preferences are not.
Setup is a few hours, one-time, and compounds across every feature and every new hire.

Conclusion

Setting up Claude Code for a NestJS monorepo isn't about making Claude smarter — it's about eliminating guesswork. A codebase with dozens of modules, hundreds of DTOs, and custom guards and adapters is genuinely ambiguous without context, and Claude's reasonable defaults won't match your conventions.

The investment is small and one-time: a focused CLAUDE.md for routing and prohibitions, a few rules files for hard constraints, and one or two skills for your most repeated tasks. After that, Claude generates code that looks like your team wrote it — not like someone who just read the NestJS docs.

DEV Community: Harshit Rathod

Beyond Vibe Coding: From AI-Assisted Coding to Agentic SDLC Automation

Agentic SDLC at a Glance

Key Takeaways

Quick Answer: What Is Agentic SDLC Automation?

Vibe Coding vs AI Coding Assistant vs Agentic SDLC

Why Vibe Coding Stalls at the Repository Boundary

Where the Work Actually Goes

The Anatomy of an AI Development Agent

Architecture Layer 1: An Agentic CLI Plugin, Not a Service

Architecture Layer 2: MCP as the Tool Boundary

Architecture Layer 3: Rules as a Contract, Read Fresh Every Run

Architecture Layer 4: Skills Loaded on Demand

Why On-Demand Conventions Matter More Than They Sound

Architecture Layer 5: Model Routing by Cognitive Load

Dependency-Aware Execution: One Chain, Not a Tree

The Execution Order, and Why It's That Order

Stacked Branches: One MR Per Ticket

Verification and Guardrails Instead of Blind Autonomy

The Full Guardrail Set

Measuring the Impact

Reading These Numbers Honestly

Lessons Learned: Mistakes That Cost Us Time

Walkthrough: One Story, End to End

The Pattern, Generalized

FAQ

Key Takeaways (Recap)

Conclusion

Further Reading

Why Large Codebases Drain Your AI Token Budget and How to Fit It

Key Takeaways

Quick Answer

The Problem: Context Budget Is a Finite Resource

Where the Tokens Actually Go

1. Exploratory File Reads

2. Convention Re-derivation

3. Wrong-Service Placement and Corrections

4. Pattern Violations and Regeneration

5. Conversation History Accumulation

The Fix: Externalize Knowledge, Don't Re-Derive It

CLAUDE.md: Replace Exploration With Declaration

What to Include

Service Routing Decision Table

Conventions That Would Otherwise Be Re-Derived

Response Shape

What to Exclude

Rules: Prevent Regeneration at the Source

Token Cost of a Rule vs. a Correction

High-Value Rules for NestJS Projects

Skills: Keep Templates Out of Always-On Context

Token Budget Impact of Skills

Skill Structure

Architecture: Per-Service CLAUDE.md Files

Measuring the Impact

Without Configuration

With CLAUDE.md + Rules + Skills

Common Mistakes That Maximize Token Waste

Real-World Example: Token Budget on a Feature Request

Summary: The Token Budget Formula

FAQ

Key Takeaways (Recap)

Conclusion

Further Reading

Claude Code for NestJS Monorepos: A Practical Setup Guide

Key Takeaways

Quick Answer

The Problem: Why Claude Struggles With Large NestJS Projects

Why This Problem Exists

Repository Structure

Step-by-Step: Configuring Claude Code for NestJS

Step 1 — Install Claude Code

Step 2 — Create CLAUDE.md

The Root CLAUDE.md

Service-Level CLAUDE.md

Step 3 — Add Rules

Rule: Prevent N+1 Queries

Rule: Permission Checks

Rule: Import Style

Other Rules Worth Defining

Step 4 — Build Skills

Recommended `.claude/` layout