Spec/Agent-Driven SDLC

With Optional LangGraph Loop if not using Claude Code

How a committed Markdown document becomes your single source of truth — and how Claude Code’s agentic runtime, directed by specialized subagents and slash commands, closes the loop from requirements to production feedback

Spec-Driven SDLC is the practice of driving your entire software development lifecycle — architecture, implementation, review, testing, deployment, and feedback — from a single versioned specification document committed to your repository. Every agent reads it before acting. Every agent writes back to it when it learns something new.

Executive Summary

The pattern explored in this article is called Spec-Driven SDLC: one living PRD.md document, committed to git, drives a fleet of eight specialized AI agents through the full software lifecycle. Architecture agent, design agent, feature agent, review agent, test agent, bug agent, deploy agent, feedback agent — each reads the spec before acting, each writes its output back to the repository.

The runtime that makes this real is Claude Code — Anthropic’s terminal-based agentic coding CLI. Claude Code is a multi-turn, tool-using agent that reads files, writes code, runs shell commands, interprets output, and continues acting — directed entirely by your .claude/ configuration. You write specifications. Claude Code executes them.

Loop engineering is how we keep this system self-correcting: the implement→review→test cycle is a directed loop, where state from each step (test failure, review findings) feeds the next iteration. Understanding loop engineering — what state flows between steps, when cycles terminate, when humans must intervene — is what separates a reliable automated pipeline from an unpredictable one.

This article builds a real system: BookAI, an AI-powered online bookstore, using Java 25 LTS, Spring Boot 4.0, React 18, FastAPI, and LangChain. Every command file, every subagent definition, and every LangGraph snippet shown here is real and runnable.

By the end you will understand:

• How to write a PRD that agents can act on without ambiguity
• The precise difference between Claude Code subagents (.claude/agents/) and slash commands (.claude/commands/)
• How Claude Code’s agentic runtime is directed by your .claude/ files — not the other way around
• Optional LangGraph and Python based loop code.
• How the feedback loop closes the cycle from production KPIs back to the spec

The Problem with Traditional SDLC

Traditional software development has a document problem. You write a PRD. An architect interprets it into a design doc. A tech lead interprets that into tickets. Developers interpret tickets into code. QA interprets code into test cases.

At every interpretation step, intent leaks. By the time the fifth engineer touches a feature, the original “why” is gone. The PRD is stale. The design doc doesn’t match the code. The tickets reference Confluence pages that 404.

This is not a people problem. It is an architecture problem. The document and the code live in separate systems, maintained by different people, with no enforced relationship between them.

Spec-Driven SDLC addresses this architecturally. Every Claude Code session reads PRD.md before acting. The document is in the critical path of every code change, every review, every deployment. It cannot drift silently — agents notice when they cannot derive a decision from the spec, and they surface the ambiguity as an open question.

The Core Idea — The Document IS the System

This pattern borrows deliberately from two established practices:

Infrastructure as Code (Terraform, CloudFormation): your infrastructure is described in files committed to git. The file is the truth — not the AWS console, not a wiki page, not someone’s memory. The infra agent (Terraform) reads the file and derives the actual infrastructure from it.

Spec-Driven SDLC applies this to the entire SDLC: PRD.md is not a document about the system — it is the system's authoritative specification. Agents read it, derive their decisions from it, and write back to it.

PRD.md  ──drives──►  /init-architecture  ──produces──►  ARCHITECTURE.md
                                                               │
                                              /plan-waves  ────┘
                                                    │
                                              WAVES.md (TASK-001..N)
                                                    │
                                         /implement-task TASK-001
                                                    │
                               Claude Code directs the loop:
                            implement → review → test → retry/done
                                                    │
                                             production runs
                                                    │
                                        /run-feedback-loop
                                                    │
                                     FEEDBACK.md (human-reviewed proposals)
                                                    │
                              human promotes proposals to PRD.md  ──►  repeat

Understanding Claude Code — The Agentic Runtime

Before anything else, you need a precise mental model of what Claude Code does and what it does not do. This is the most consequential section in the article.

What Claude Code provides natively

Claude Code is a terminal-based agentic coding CLI. It provides:

• Multi-turn execution — it continues acting across multiple steps without you re-prompting
• Tool use — it reads files, writes files, runs shell commands (mvn test, pytest, git diff, docker build), and reads their output
• Context persistence — state from earlier steps (a test failure, a file it just wrote) is available in subsequent steps
• Interruption + resumption — it pauses when it genuinely needs input and resumes when you respond

This is the runtime. It is capable of looping, retrying, and self-correcting — but it does not do so intelligently on its own. The intelligence of the loop comes from your .claude/ configuration.

What your .claude/ files provide

The .claude/ directory contains two types of files. Understanding the distinction between them is critical — they serve fundamentally different roles:

**.claude/agents/ — Subagents (isolated specialists)**

Each file in .claude/agents/ defines a subagent: a specialized Claude instance that runs in its own isolated context window, separate from the main conversation. When a subagent is invoked, it:

• Spins up a fresh Claude instance
• Loads its own system prompt (the .md file content)
• Executes its task with the tools it is given
• Returns its output to the caller
• Terminates

The isolation is the key property. A subagent’s context is not polluted by the main conversation history. A review subagent reading a 2,000-line service sees only what it needs to see. This makes subagents reliable for focused, repeatable tasks.

**.claude/commands/ — Slash commands (orchestration triggers)**

Each file in .claude/commands/ defines a slash command: a manual trigger you invoke with /command-name. Commands run in the main conversation context. They define: what to read, which subagent to invoke, what output to expect, what pre-conditions to check. Commands are the orchestration layer — they direct the loop. Subagents are the workers — they do the actual task.

A note on versions: .claude/commands/ is the original format and continues to work. As of Claude Code v2.1.101 (April 2026), .claude/skills/ is the newer recommended format. This article uses .claude/commands/ for clarity and broad compatibility — the concepts transfer directly to skills.

The relationship in one sentence: a slash command is WHEN, a subagent is WHO and WHAT.

You type: /implement-task TASK-018
    │
    ▼
.claude/commands/implement-task.md  (orchestration — WHEN and HOW)
    │  reads WAVES.md, ARCHITECTURE.md
    │  invokes feature subagent
    ▼
.claude/agents/feature-agent.md  (isolated worker — WHO and WHAT)
    │  its own context window
    │  writes source files to disk
    │  returns FILES_WRITTEN summary
    ▼
Command receives result
    │  invokes review subagent
    ▼
.claude/agents/review-agent.md  (isolated worker)
    │  reads the files just written
    │  returns APPROVED or CHANGES_REQUESTED
    ▼
Command routes: APPROVED → run tests, CHANGES_REQUESTED → re-invoke feature subagent

The loop is directed, not autonomous

This is the most important clarification in the article. The implement→review→test loop is not a built-in Claude Code behavior. It is the behavior that our .claude/commands/implement-task.md file specifies. The command file tells Claude Code:

1. Read the task
2. Invoke the feature subagent to implement it
3. Invoke the review subagent to check the output
4. Run the test suite via shell
5. If tests fail, re-invoke the feature subagent with the failure as context
6. After 3 failures, pause and ask for human guidance

Without that command file, Claude Code would implement a task in one shot and stop. The loop is the spec. Claude Code is the runtime that executes it.

A Note Python, LangGraph based Loop and the agents/ Folder

If you are using Claude Code, you do not need the Python LangGraph Loop to build the application.

The repository contains Python files — feature_loop.py, review_loop.py — that implement the same loop structure using LangChain and LangGraph. These are learning artifacts. Loop engineering is the practice of designing agent execution as an explicit state machine: what state flows between steps, how conditional edges route execution, where cycles terminate, and where humans must intervene.

# feature_loop.py — the loop expressed in Python (learning artifact)
# This is what Claude Code's runtime does internally, made explicit

class FeatureLoopState(TypedDict):
    task_id: str
    review_result: str      # flows from self_review to re-implement
    test_output: str        # flows from run_tests to decide next step
    retry_count: int        # increments on each failed attempt

# Conditional edge — this is the routing logic Claude Code performs
def route_after_review(state) -> Literal["run_tests", "implement"]:
    if state["review_status"] == "APPROVED":
        return "run_tests"
    return "implement"  # loop back — review findings are now in state

Reading feature_loop.py gives you the mental model: what state flows between steps, how conditional edges route the execution, how the retry counter gates the human pause. The LangGraph graph is the clearest formalism for expressing this. But Claude Code already implements this runtime — you do not run both.

Three properties make this loop effective:

State accumulation. When the feature subagent re-runs after a failed test, it receives the test output in its context. It knows exactly what broke and why — not just that something failed. This transforms retry from a dumb repetition into an intelligent correction.

Conditional routing. The loop does not blindly repeat. It routes differently based on the outcome of each step. Review approved → proceed to tests. Tests failed → fix and retry. Three failures → pause. This is a decision graph, not a pipeline.

The human gate as a first-class node. After three failures, the loop does not silently abort or infinitely retry. It surfaces full state to the human and waits. The human provides a hint or makes a decision to skip the task. This keeps humans accountable for the quality of the output without requiring them to supervise every step.

The Tech Stack — This Example, Not a Prescription

The spec-driven SDLC pattern and Claude Code loop engineering covered in this article are completely stack-agnostic. The same PRD structure, the same .claude/agents/ subagent definitions, the same slash command loop — all of it applies equally to a Node.js monolith, a Go microservice, a Django API, or a Ruby on Rails app. If you are reading this as a Go developer, the pattern is yours. Swap the tech, keep the method.

For concreteness, BookAI uses the following stack. The choices are what one team picked for one project — not recommendations:

Backend: Java 25 LTS with Spring Boot 4.0, five Spring Boot microservices plus a Spring Cloud Gateway, built with Maven multi-module reactor. Python 3.12 with FastAPI for the AI recommendation service.

Data: PostgreSQL 16 (per-service schemas, Flyway migrations), Redis 7 (session and cache), Elasticsearch 8 (full-text search).

Auth: Keycloak 25 with OAuth2/OIDC in production; HTTP Basic with in-memory users for local development. Both profiles are defined in PRD.md section 8 and enforced by the architecture and review subagents.

AI/LLM: Ollama with gemma4:e4b locally, Claude claude-sonnet-4-6 in production, toggled by a single environment variable in llm_factory.py.

Frontend: React 18, Vite, TanStack Query, Zustand, Tailwind.

SDLC tooling: Claude Code as the agentic runtime. Everything else in the SDLC — the loop, the review gate, the task tracking — is directed by .md files in .claude/.

That is all the stack coverage this article needs. The rest is about the method.

The PRD/SPEC Document — Anatomy and Purpose

docs/PRD.md is committed to the repository root. Every subagent reads the sections relevant to its role before acting. Every section has a purpose that maps to a specific agent or command.

A PRD that subagents can act on requires three properties:

Precision over prose. “The system should be fast” produces vague architecture. “Search API p95 latency < 200ms under 100 concurrent users (NFR-001)” gives the architecture subagent a constraint to derive technology choices from. The review subagent checks NFR-001 compliance on every search endpoint implementation.

Unique IDs on every requirement. FR-001 through FR-N and NFR-001 through NFR-N. Every TASK in WAVES.md references a FR. Every line of generated code traces back to a numbered requirement. This traceability is structural, not documentary — it cannot drift.

A living change log. Every PRD change gets a version bump, date, and description. Subagents check this first. If the spec changed since their last run, they re-derive their outputs.

Various sections of PRD.md:

## 1.  Vision & problem statement       ← all subagents read first
## 2.  User personas                    ← design subagent, acceptance criteria
## 3.  Functional requirements (MoSCoW) ← wave planning, feature subagent
## 4.  Non-functional requirements      ← architecture subagent, review checklist
## 5.  Data entities & relationships    ← seeds data model in ARCHITECTURE.md
## 6.  API surface (high level)         ← REST API table in ARCHITECTURE.md
## 7.  UX principles & constraints      ← design subagent, wireframes
## 8.  Security & compliance            ← all services, gateway, review checklist
## 9.  Technology preferences           ← invariant stack (never overridden silently)
## 10. Success metrics & KPIs           ← feedback_loop.py compares against weekly
## 11. References & prior art           ← subagents fetch these URLs before acting
## 12. Change log                       ← subagents check version before acting

How precision flows from PRD to code:

# PRD.md section 8:
| NFR-007 | Security | JWT RS256-signed; access token TTL 15 minutes |
| NFR-008 | Security | Refresh token TTL 7 days, stored in HttpOnly cookie |

// SecurityConfig.java — generated by Claude Code, directed by the feature subagent,
// citing NFR-007 and NFR-008 in comments:
.tokenSettings(TokenSettings.builder()
    .accessTokenTimeToLive(Duration.ofMinutes(15))   // NFR-007
    .refreshTokenTimeToLive(Duration.ofDays(7))       // NFR-008
    .build())

The traceability is in the code, not in a separate document that will go stale.

The Subagent Fleet — Eight Specialized Workers

Eight subagent files live in .claude/agents/. Each is invoked by one or more slash commands. Each runs in its own isolated context window. Each has exactly one job.

The design principle: specialists, not generalists. A subagent that both implements and reviews code does both poorly. The review subagent can apply a ruthless security checklist that would be counterproductive if the feature subagent applied it to itself mid-implementation.

Architecture Subagent (.claude/agents/architecture-agent.md)

Invoked by: /init-architecture Reads: All of PRD.md Writes: ARCHITECTURE.md — 11 sections including Mermaid ERD, Java interface stubs, full REST API surface, OAuth2 sequence diagrams, HLD, LLD notes, Maven reactor structure

Critical rule: every technology decision must cite the PRD section that drove it. Ambiguities are filed as [AQ-N] open questions — never silently resolved.

Note: You can implement the architecture agent to produce separate HLD, LLD, Object and Data model files rather than combining all and keeping everything in a single ARCHITECTURE.md file.

Feature Subagent (.claude/agents/feature-agent.md)

Invoked by: /implement-task command (via the loop) Reads: Specific TASK from WAVES.md + relevant ARCHITECTURE.md sections + existing source files (for pattern consistency) Writes: Complete, compilable source files — never truncated, never stubbed

Review Subagent (.claude/agents/review-agent.md)

Invoked by: /review-code command, and by /implement-task during its loop Reads: Source files written by the feature subagent + PRD security section + ARCHITECTURE.md contracts Writes: Structured review report with file:line citations

Five-category checklist: spec compliance, security (hard block — any IDOR or missing @PreAuthorize always produces CHANGES_REQUESTED), Spring Boot 4 compliance, code quality, test coverage. Similar checks are in place for the frontend code.

The human gate is explicit in the subagent definition:

## Human gate (non-negotiable)
This subagent NEVER autonomously triggers re-implementation.
It writes findings and waits. The human reads the report
and runs /approve or /reject. Nothing proceeds automatically.

Test Subagent (.claude/agents/test-agent.md)

Invoked by: /run-tests command, and by /implement-task during its loop Writes: Unit tests + Testcontainers integration tests

Never uses H2 in memory — always Testcontainers with real PostgreSQL 16. H2 silently ignores PostgreSQL-specific types (UUID, JSONB) and SQL constructs. Tests cover: happy path, 404, 400 validation, 401 no auth, 403 wrong role, 403 IDOR, graceful 5xx on downstream failure.

Bug Subagent (.claude/agents/bug-agent.md)

Invoked by: /file-bug "<sentry payload>" Writes: Structured [BUG-NNN] ticket appended to WAVES.md

Seven-step triage: parse error → identify source line from stack trace → determine severity (P1/P2/P3 by user impact, not by how alarming the message sounds) → construct minimal reproduction → check duplicates → assign number → append ticket. Key constraint: never speculate on root cause beyond what the stack trace supports.

Deploy Subagent (.claude/agents/deploy-agent.md)

Invoked by: /deploy <service> <env> Writes: ECS deployment, smoke test results

Pre-flight checklist: tests passed, review approved, no open P1 bugs, Flyway migrations are backwards-compatible, Docker builds clean with --no-cache. Three smoke tests after every deployment. Auto-rollback on any failure — rollback record appended to FEEDBACK.md.

Feedback Subagent (.claude/agents/feedback-agent.md)

Invoked by: /run-feedback-loop — or via feedback_loop.py on a cron schedule Reads: CloudWatch metrics, Sentry weekly summary, analytics events, PRD section 10 KPIs Writes: Weekly report appended to FEEDBACK.md

For any KPI at BELOW_TARGET or CRITICAL vs its PRD target, proposes a specific new functional requirement. Never modifies PRD.md directly. Proposals are for human review. Only intentional human decisions change the spec.

The Slash Command Interface

Each command is a Markdown file defining the complete protocol for that operation. Commands are the orchestration layer — they decide when to invoke which subagents, in what order, with what context.

The /implement-task command is the most important — it contains the complete loop definition:

# /implement-task

## The loop this command directs
1. Read TASK-$ARGUMENTS from WAVES.md — validate status and dependencies
2. Load feature subagent context: ARCHITECTURE.md + existing source + PRD FR
3. Invoke feature subagent → writes source files to disk
4. Invoke review subagent → reads files, applies checklist
5. If CHANGES_REQUESTED: re-invoke feature subagent with review findings in context
6. Run tests: mvn test -pl services/<service> (or pytest for ai-service)
7. If tests PASS: update TASK status to COMPLETE → done
8. If tests FAIL: re-invoke feature subagent with test failure in context, increment retry_count
9. After 3 failures: print full state, pause for human guidance

## On pause
IMPLEMENTATION_PAUSED: TASK-<ID>
[test output and review findings printed]

Options:
  /implement-task TASK-<ID> --hint "the @PreAuthorize needs hasRole('ADMIN')"
  /implement-task TASK-<ID> --reset
  /file-bug "<describe the blocker>"

The pause on three failures is the human-in-the-loop gate. The state at that point — which tests failed, what the review found, which files were written — is printed in full. You make an informed decision. The loop resumes with your guidance in context.

Wave-Based Implementation

The wave planning command decomposes the PRD into a phased delivery plan. Each wave is a shippable increment — real users could use it before the next wave begins.

Wave 1 — Foundation (Weeks 1–3): Repository scaffold, CI/CD skeleton, auth service (register, login, JWT with RS256), core database schemas, basic book catalog CRUD, React app shell with routing and Tailwind design tokens.

Wave 2 — Core Commerce (Weeks 4–6): Elasticsearch-backed search with filters, book detail pages, cart service, checkout with mock payment, order management, confirmation email stubs.

Wave 3 — AI Features (Weeks 7–10): Recommendation engine (LangChain chains in ai-service calling Ollama/Claude), semantic search, reading history capture, review system with AI summary, personalised homepage.

Wave 4 — Polish + Operations (Weeks 11–13): Admin dashboard, CDN and Redis caching, monitoring dashboards, WCAG 2.1 AA accessibility audit, load testing.

Every task in WAVES.md is a complete specification for one subagent invocation:

### [TASK-018] Implement BookService.getRecommendations()
- Wave: Wave 3
- Service: book-service
- Subagent: feature-agent
- PRD reference: FR-010
- Architecture reference: Section 5 (BookService interface)
- Depends on: TASK-014, TASK-015
- Status: PLANNED
- Acceptance criteria:
  - AC-1: Takes userId: UUID, limit: int (default 10)
  - AC-2: Returns List<RecommendedBookResponse> with reason field on each item
  - AC-3: Falls back to popular books when reading history is empty
  - AC-4: Handles ai-service timeout gracefully (< 3s, then fallback)
  - AC-5: Returns 403 Forbidden when accessing another user's recommendations

A Real Claude Code Session

Generating architecture and panning waves by invoking /init-architecture and /plan-waves from Claude code.

Here is what a complete task cycle looks like.

You open Claude Code:

cd /bookstore-ai
claude

You type one slash command:

/implement-task TASK-003

TASK-003 is “Implement POST /api/auth/register in user-service.”

Claude Code reads the command file, which directs it to: load the feature subagent, read TASK-003 from WAVES.md, read the UserService interface from ARCHITECTURE.md, read existing source files in user-service/ for pattern consistency.

The feature subagent writes complete files to disk:

// RegisterRequest.java — Java Record (as required by feature-agent.md rules)
public record RegisterRequest(
    @NotBlank(message = "Email is required")
    @Email(message = "Must be a valid email address")
    @Size(max = 255)
    String email,

    @NotBlank(message = "Password is required")
    @Size(min = 8, max = 72, message = "Password must be 8–72 characters")
    String password,

    @NotBlank @Size(max = 100) String firstName,
    @NotBlank @Size(max = 100) String lastName
) {}

// UserServiceImpl.java — constructor injection, no @Autowired (feature-agent.md rule)
@Service @Transactional @RequiredArgsConstructor @Slf4j
public class UserServiceImpl implements UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final UserMapper userMapper;

    @Override
    public UserResponse register(RegisterRequest request) {
        if (userRepository.existsByEmailIgnoreCase(request.email())) {
            throw new EmailAlreadyExistsException("An account with this email already exists");
        }
        var user = User.builder()
            .email(request.email().toLowerCase())   // case-insensitive deduplication
            .passwordHash(passwordEncoder.encode(request.password()))
            .role(UserRole.ROLE_CUSTOMER)
            .build();
        var saved = userRepository.save(user);
        log.info("User registered: id={}", saved.getId()); // NFR-009: no PII in logs
        return userMapper.toResponse(saved);
    }
}

The command then directs Claude Code to invoke the review subagent — this happens because the command file specifies it, not because it is a default Claude Code behavior:

Review subagent — applying checklist from review-agent.md:
✅ Constructor injection via @RequiredArgsConstructor (no @Autowired on fields)
✅ Password not logged — only UUID (NFR-009: no PII in logs)
✅ Input validation: @Valid + Jakarta constraints on record
✅ email.toLowerCase() — prevents duplicate accounts with different casing
✅ EmailAlreadyExistsException maps to 409 in @ControllerAdvice
✅ Spring Data JPA — no SQL injection risk
REVIEW_COMPLETE: APPROVED

Tests run (also directed by the command file):

mvn test -pl services/user-service
[INFO] Tests run: 8, Failures: 0, Errors: 0, Skipped: 0

Command reports and closes the loop:

FILES_WRITTEN:
- services/user-service/.../dto/RegisterRequest.java
- services/user-service/.../service/UserServiceImpl.java
- services/user-service/.../service/UserServiceImplTest.java
- services/user-service/.../controller/UserControllerIT.java
- services/user-service/.../resources/db/migration/V2__add_users_table.sql

TASK_COMPLETE: TASK-003

WAVES.md status updated to COMPLETE. Dependent tasks unlocked. You ran one slash command.

The Feedback Loop — Closing the Cycle

The feedback loop is what turns this from a one-shot build tool into a continuous improvement system. It connects production signals back to the spec.

As established earlier, feedback_loop.py runs on a cron schedule — not through interactive Claude Code sessions. Every Monday it:

1. Observes — parses CloudWatch latency metrics, Sentry error summary, analytics conversion events
2. Analyzes — compares each KPI against its PRD section 10 target (EXCEEDING / ON_TARGET / BELOW_TARGET / CRITICAL / NO_DATA)
3. Acts — for BELOW_TARGET or CRITICAL KPIs, proposes a specific new FR; for recurring errors, escalates a bug ticket
4. Writes — appends a structured report to FEEDBACK.md (proposals only — never touches PRD.md)

The following is an illustrative example of what a weekly report looks like (not real production data):

## Feedback Report — Week 3 (illustrative example)

### KPI Scorecard
| Metric | PRD Target | Actual | Status | Trend |
|--------|-----------|--------|--------|-------|
| Recommendation CTR | ≥ 8% | 11.3% | ✅ EXCEEDING | ↑ |
| Cart-to-order conversion | ≥ 60% | 51.2% | ⚠️ BELOW_TARGET | ↓ |

### Proposed PRD Amendments
<!-- Human reviews — manually promotes to PRD.md if approved -->
[FR-PROP-001] Display shipping cost estimate on the book detail page,
before the user adds to cart.
Rationale: Heatmap analysis (illustrative) shows high abandonment at
the checkout shipping reveal step.
Related KPI: Cart-to-order conversion
Suggested wave: Wave 3

Key design decision: proposals, never changes. The feedback subagent is constrained by its definition to write FEEDBACK.md only. You read the report and decide what becomes a real requirement. Only intentional human decisions change PRD.md. This keeps the spec authoritative.

When you promote a proposal:

1. Edit PRD.md section 3 — add the new FR with the next ID
2. Update the change log (section 12) with version bump
3. Run /init-architecture — architecture subagent re-derives affected sections
4. Run /plan-waves — new TASK entries appear in the active wave

The cycle closes: build → measure → learn → update spec → rebuild. The system improves in directions you choose.

Trade-offs and Alternatives

What Spec-Driven SDLC does well

Structural traceability. Every TASK references a FR. Every FR references a PRD section. Every generated file cites the TASK and FR it implements. In traditional projects, this traceability exists in documentation that drifts. Here it is enforced by the loop.

Consistent quality gates. The review subagent applies the same security checklist on every task. The security requirements in NFR are never forgotten in week 8 when the team is under deadline pressure.

Living requirements. The feedback loop means PRD.md reflects production reality after launch, not just original intent before it.

Low tooling overhead. The setup is installing Claude code and your existing development infrastructure. The intelligence is in .md files in your repository.

What this approach costs

PRD quality is the bottleneck. Claude Code is only as precise as the spec it reads. Vague requirements produce vague code. Writing precise, ID-tagged, MoSCoW-prioritized requirements takes longer than writing tickets. It pays back on any project beyond a one-person weekend build.

Non-determinism needs test coverage. The feature subagent produces slightly different output across runs. The review loop catches behavioral issues. Test coverage catches correctness issues. Both are needed.

Subagent definition maintenance. Your .claude/agents/ files are system prompts. They need updating as the project evolves — rules correct for Wave 1 may need revision by Wave 3 as the codebase grows.

The key differentiator using Claude code is the .claude/ directory pattern. Subagent definitions and command files are version-controlled, code-reviewed, and shared across the entire team. Any developer who clones the repository gets the same agent fleet — not a personal configuration, a team standard.

Key Takeaways

1. Spec-Driven SDLC is an architectural choice, not a tool choice. The discipline is writing a precise, versioned, ID-tagged specification that every agent reads before acting. The tool (Claude Code) executes it.

2. Claude Code provides the runtime; your .claude/ files provide the intelligence. Without well-defined command files and subagent definitions, Claude Code implements tasks in one shot and stops. The implement→review→test loop is the spec written in .md files.

3. Subagents and slash commands are different things. .claude/agents/ = isolated specialist workers with their own context windows. .claude/commands/ = orchestration triggers that direct those workers. Commands define WHEN; subagents define WHO and WHAT.

4. The LangGraph Loop is a teaching tool, not a dependency. feature_loop.py exists to make the loop's mechanics explicit. Reading it builds the mental model. Claude Code already runs this loop natively.

5. Python has two legitimate jobs. The scheduled feedback_loop.py (cron, no interactive Claude Code) and the ai-service (application code, always needed). Everything else in agents/ is either a learning artifact or configuration reused by ai-service.

6. Human gates are features, not limitations. The review gate and the feedback proposal model keep humans accountable for quality and direction. The loop is not trying to replace human judgment — it is trying to make human judgment cheaper to apply.

7. The feedback loop closes the system. Software development is not a one-shot process. The weekly feedback report that surfaces KPI drift and proposes PRD amendments is what turns this into continuous improvement rather than one-time code generation.

The complete BookAI repository — PRD, subagent definitions, slash commands, Spring Boot 4 services, React frontend, and CI/CD pipelines — is at https://github.com/dasansuman/bookstore-ai

Note: Necessary structures and files for spec-driven SDLC are committed. Only empty structures are available for services and frontend which has to be implemented following this guide.