AI-Driven Development with Claude Code

Develop in Production like Tony Stark with his J.A.R.V.I.S.

This chapter teaches you to use Claude Code with specialized subagents for professional development. The core concept:

Philosophy of AI-Assisted Development

NOT: "AI programs for me"
YES: "I program WITH AI"

You always maintain control. AI suggests, you decide.

Installation and Setup

Prerequisites

Step 1: Configure API Key

# Environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

# Or add permanently
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc

Step 2: Start Claude Code

# Navigate to your project
cd /path/to/your/project

# Start Claude Code
claude

Step 3: Initialize Project with the Architect

> Use scope-rule-architect to create TaskFlow app structure with:
- React 19, TypeScript, Vitest, ESLint, Prettier, Tailwind CSS
- Features: task-management, project-filtering, export-functionality
- Shared: components (Button, Modal, Badge), hooks (useLocalStorage), utils (formatters)
- No backend required, localStorage only

This will automatically create:

Scope Rule Architecture

Fundamental Principles

1. Scope Rule - The Unbreakable Rule

"Scope determines structure"

2. Screaming Architecture - The Structure that SCREAMS

Your structure must communicate IMMEDIATELY what the application does.

✅ GOOD - Screams functionality:

src/
  features/
    shopping-cart/        # It's a cart!
    user-authentication/  # Authentication!
    task-management/      # Task management!

❌ BAD - Technical grouping:

src/
  components/  # What does the app do?
  containers/  # Says nothing
  hooks/       # Purely technical

3. Container/Presentational Pattern

Decision Framework

  1. Identify scope: How many features use it?
  2. Apply rule: 1 feature = local, 2+ = global
  3. Validate: Does the structure scream what the app does?

Example Structure

src/
  features/
    task-management/
      task-management.tsx     # Main container
      components/
        TaskList.tsx          # Secondary container
        TaskItem.tsx          # Presentational
      services/
        TaskService.ts
      hooks/
        useTasks.ts
      models.ts

  shared/                     # GLOBAL = 2+ features
    components/
      Button.tsx
      Modal.tsx
    hooks/
      useLocalStorage.ts
    utils/
      formatters.ts

  infrastructure/             # Cross-cutting
    api/
    auth/
    monitoring/

CLAUDE.md File

# CLAUDE.md

## Architecture: Scope Rule
- **Global**: Used by 2+ features
- **Local**: Used by 1 feature only

## Tech Stack
- React 19 + TypeScript
- Zustand for state
- React Query for server state
- Tailwind CSS
- Vitest + React Testing Library
- ESLint + Prettier (auto-applied)

## TDD Development Workflow

### Phase 1: Architecture & Planning
1. scope-rule-architect: Design structure - USE for new features
2. react-mentor: Architectural guidance - USE for complex decisions
3. git-workflow-manager: Commit - USE after each phase

### Phase 2: Test-Driven Development
4. tdd-test-first: Create tests - USE for each functionality
5. git-workflow-manager: Commit RED phase
6. react-test-implementer: Implement - USE after tests fail
7. git-workflow-manager: Commit GREEN phase

### Phase 3: Quality & Security
8. security-auditor: Audit - USE before main merge
9. git-workflow-manager: Commit fixes
10. accessibility-auditor: WCAG - USE after UI complete
11. git-workflow-manager: Commit improvements

## Git Strategy (NO Claude mentions)
- Architecture: "feat: add [feature] architecture"
- Tests: "test: add [feature] tests (RED)"
- Implementation: "feat: implement [feature] (GREEN)"
- Security: "fix: security improvements"
- A11Y: "feat: improve accessibility"

## RULES
- NEVER write code without concrete functionality
- NEVER implement without failing tests
- NEVER mention Claude in commits
- ALWAYS apply ESLint + Prettier

Subagent System

Create Subagents with /agents

> /agents

Interactive menu to:

The 7 Main Agents

1. scope-rule-architect

Architecture specialist for Scope Rule. Decides component placement (global if 2+ features, local if 1).
Creates project structure, installs React 19, TypeScript, Vitest, ESLint, Prettier.
Container components must have same name as feature. Structure must scream functionality.
USE WHEN: Starting new features or projects.

2. react-mentor

React patterns expert. Provides guidance on architectural decisions, performance optimizations,
and best practices. Knows React 19, TypeScript, hooks patterns, state management.
USE WHEN: Complex architectural decisions needed.

3. tdd-test-first

TDD specialist that ALWAYS writes tests FIRST. Creates comprehensive test suites with Vitest
and React Testing Library. Tests must fail initially (RED phase). Covers happy paths,
edge cases, error states. Tests based on concrete user stories and acceptance criteria.
USE WHEN: Starting any new functionality (always before coding).

4. react-test-implementer

Implementation specialist. Writes minimal code to pass ALL tests. Follows Container/Presentational
pattern. Applies ESLint + Prettier automatically. Uses React 19, TypeScript, Zustand, React Query.
USE WHEN: After tests are failing (RED phase complete).

5. security-auditor

Security expert checking OWASP Top 10, XSS, CSRF, authentication issues. Reviews JWT implementation,
input validation, API security. Runs npm audit. Checks for exposed secrets.
USE WHEN: Before merging to main branch.

6. accessibility-auditor

WCAG 2.1 AA compliance expert. Checks keyboard navigation, ARIA labels, screen reader support,
color contrast. Global components must be perfect. Feature components follow semantic HTML.
USE WHEN: After UI features are complete.

7. git-workflow-manager

Git specialist for conventional commits. NEVER mentions Claude Code or AI collaboration.
Uses format: feat|fix|test|docs|refactor|chore(scope): description.
Creates professional PR descriptions. Manages semantic versioning.
USE WHEN: After each development phase for commits.

Practical Project - TaskFlow

Project Specifications File

IMPORTANT: Before starting development, create a PROJECT_SPECS.md file with all project specifications. This file is fundamental for Claude Code and subagents to have complete context.

PROJECT_SPECS.md Content

# TaskFlow - Project Specifications

## Project Description
TaskFlow is a personal task manager that allows organizing work with projects, priorities, and statuses. Everything is stored in localStorage.

## User Stories

### Epic 1: Basic Task Management

#### US-001: View task list
As a user, I want to see a list of tasks to know my pending work

**Acceptance Criteria:**
- Show empty list with "No tasks" message initially
- Each task displays: title, priority (color badge), status
- Tasks sorted by creation date (newest first)
**Technical Notes:** Use mocked data initially

#### US-002: Create new task
As a user, I want to create a new task to add pending work

**Acceptance Criteria:**
- Form with fields: title (required, 3-100 chars), description (optional), priority (select: low/medium/high)
- "Create" button disabled if title invalid
- Task appears immediately in list after creation
- Clear form after successful creation
**Validations:** Title between 3-100 characters

[... rest of user stories ...]

## Data Structure
Interface Task {
  id: string;        // UUID
  title: string;     // 3-100 chars
  description?: string;
  priority: 'low' | 'medium' | 'high';
  status: 'TODO' | 'IN_PROGRESS' | 'DONE';
  project: 'Personal' | 'Work' | 'Study' | 'General';
  createdAt: Date;
  updatedAt: Date;
}

## Business Rules
- Status transitions: TODO → IN_PROGRESS → DONE (and back)
- Default project is "General"
- Priority colors: low=green, medium=yellow, high=red
- All data persisted to localStorage key: taskflow_tasks

Using the file in commands

When using any subagent, reference the file to provide complete context:

> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-002

Or add it to CLAUDE.md so it's always available:

# CLAUDE.md

## Project Context
@PROJECT_SPECS.md contains all user stories and requirements

[rest of content...]

Description

TaskFlow is a personal task manager that allows organizing work with projects, priorities and states. No backend, everything in localStorage.

Complete User Stories

Epic 1: Basic Task Management

US-001: As a user, I want to view a list of tasks to know my pending work

US-002: As a user, I want to create a new task to add pending work

US-003: As a user, I want to edit an existing task to correct information

US-004: As a user, I want to delete a task to remove completed work

Epic 2: States and Workflow

US-005: As a user, I want to change task status for progress tracking

US-006: As a user, I want to filter tasks by state for specific focus

Epic 3: Projects

US-007: As a user, I want to organize tasks in projects for better organization

US-008: As a user, I want to filter tasks by project

Epic 4: Persistence

US-009: As a user, I want my tasks to save automatically

US-010: As a user, I want to export my tasks for backup

Data Structure

interface Task {
  id: string;         // UUID
  title: string;      // 3-100 chars
  description?: string;
  priority: 'low' | 'medium' | 'high';
  status: 'TODO' | 'IN_PROGRESS' | 'DONE';
  project: 'Personal' | 'Work' | 'Study' | 'General';
  createdAt: Date;
  updatedAt: Date;
}

Iteration Plan - Complete Workflow

Iteration 1: Setup (US-001 partial)

> Use scope-rule-architect to create initial structure
> Use git-workflow-manager to commit
COMMIT: feat: initial project setup with routing

Iteration 2: Task List (US-001)

# RED Phase - Tests
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-001
> Use git-workflow-manager to commit
COMMIT: test: add TaskList tests (RED)

# GREEN Phase - Implementation
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement TaskList (GREEN)

# Security Check
> Use security-auditor to check TaskList
IF issues found:
  > Use tdd-test-first to update tests with security requirements
  > Use react-test-implementer to fix security issues
  > Use git-workflow-manager to commit
  COMMIT: fix: security improvements for TaskList

# Accessibility Check
> Use accessibility-auditor to check TaskList
IF issues found:
  > Use tdd-test-first to update tests with a11y requirements
  > Use react-test-implementer to fix a11y issues
  > Use git-workflow-manager to commit
  COMMIT: feat: improve TaskList accessibility

Iteration 3: Create Task (US-002)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-002
> Use git-workflow-manager to commit
COMMIT: test: add CreateTask tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement CreateTask form (GREEN)

# Security Check
> Use security-auditor to check CreateTask
IF issues found:
  > Use tdd-test-first to update tests
  > Use react-test-implementer to fix issues
  > Use git-workflow-manager to commit
  COMMIT: fix: security improvements for CreateTask

# Accessibility Check
> Use accessibility-auditor to check CreateTask
IF issues found:
  > Use tdd-test-first to update tests
  > Use react-test-implementer to fix issues
  > Use git-workflow-manager to commit
  COMMIT: feat: improve CreateTask accessibility

Iteration 4: Edit Task (US-003)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-003
> Use git-workflow-manager to commit
COMMIT: test: add EditTask tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement task editing (GREEN)

# Security & A11Y Checks (same process)

Iteration 5: Delete Task (US-004)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-004
> Use git-workflow-manager to commit
COMMIT: test: add DeleteTask tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement task deletion (GREEN)

# Security & A11Y Checks (same process)

Iteration 6: States (US-005)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-005
> Use git-workflow-manager to commit
COMMIT: test: add status workflow tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement status workflow (GREEN)

# Security & A11Y Checks (same process)

Iteration 7: State Filter (US-006)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-006
> Use git-workflow-manager to commit
COMMIT: test: add status filter tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement status filtering (GREEN)

# Security & A11Y Checks (same process)

Iteration 8: Projects (US-007, US-008)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-007 and US-008
> Use git-workflow-manager to commit
COMMIT: test: add project tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement projects (GREEN)

# Security & A11Y Checks (same process)

Iteration 9: Persistence (US-009)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-009
> Use git-workflow-manager to commit
COMMIT: test: add persistence tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement auto-save (GREEN)

# Security Check (localStorage XSS prevention)
> Use security-auditor to check persistence
IF issues found:
  > Use tdd-test-first to update tests
  > Use react-test-implementer to fix issues
  > Use git-workflow-manager to commit
  COMMIT: fix: secure localStorage implementation

Iteration 10: Export (US-010)

# RED Phase
> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-010
> Use git-workflow-manager to commit
COMMIT: test: add export tests (RED)

# GREEN Phase
> Use react-test-implementer to make tests pass
> Use git-workflow-manager to commit
COMMIT: feat: implement JSON export (GREEN)

# Security & A11Y Checks (same process)

Iteration 11: Final Security & A11Y Audit

# Full Application Audit
> Use security-auditor to audit entire application
> Use accessibility-auditor for full WCAG compliance check

IF any issues found:
  > Use tdd-test-first to create/update tests for the issues
  > Use react-test-implementer to fix all issues
  > Use git-workflow-manager to commit
  COMMIT: fix: final security and accessibility improvements

Important Workflow Rule

NEVER modify code directly without updating tests first

If security or a11y find problems:

  1. First update/create tests that capture the problem
  2. Then modify code to make tests pass
  3. Commit after each change

This ensures:

Tony Stark Workflow

The Complete Loop

Tony (define) → Jarvis (orchestrate) → Agents (execute) → Review → Iterate

Complete Example: Implement US-002 (Create Task)

ACT 1: Tony Plans

> I need to implement US-002 from the project specs

ACT 2: TDD - Tests First

> @PROJECT_SPECS.md Use tdd-test-first to create tests for US-002

The subagent will read the acceptance criteria directly from the file and create appropriate tests.

ACT 3: Commit Tests (RED)

> Use git-workflow-manager to commit tests

Result: test: add CreateTask form tests (RED)

ACT 4: Implementation

> Use react-test-implementer to implement CreateTask to pass all tests

The subagent already knows what to implement because it has the failing tests.

ACT 5: Commit Implementation (GREEN)

> Use git-workflow-manager to commit implementation

Result: feat: implement CreateTask form (GREEN)

ACT 6: Security & Accessibility

> Use security-auditor to check CreateTask
> Use accessibility-auditor to verify WCAG compliance

The key is that with @PROJECT_SPECS.md each subagent has all the necessary context without needing to repeat requirements in each command.

Scripts and Automation

Package.json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "lint": "eslint . --ext ts,tsx",
    "format": "prettier --write .",

    // Claude workflows
    "ai:architect": "echo 'Use scope-rule-architect' | claude",
    "ai:test": "echo 'Use tdd-test-first' | claude",
    "ai:implement": "echo 'Use react-test-implementer' | claude",
    "ai:security": "echo 'Use security-auditor' | claude",
    "ai:a11y": "echo 'Use accessibility-auditor' | claude",

    // Full workflow
    "ai:feature": "npm run ai:test && npm run ai:implement"
  }
}

Custom Slash Commands

# Create command for optimization
echo "Analyze performance and suggest optimizations" > .claude/commands/optimize.md

# Use in Claude Code
> /optimize

Reference Commands

Basic Claude Code

# Start
claude

# Continue conversation
claude --continue

# Conversation selector
claude --resume

# Output formats
claude --output-format json

Inside Claude Code

# Manage agents
> /agents

# Reference files
> @src/components/TaskList.tsx

# Deep thinking
> Think deeply about [topic]

# Use specific agent
> Use the [agent-name] subagent to [task]

Tips and Best Practices

For User Stories

✅ Define clear acceptance criteria ✅ Include specific validations ✅ One concrete functionality per iteration

For TDD

✅ Tests first, code later ✅ Commit in each phase (RED, GREEN) ✅ Tests based on acceptance criteria

For Commits

✅ Conventional commits always ✅ NEVER mention Claude or AI ✅ One commit per workflow phase

For Architecture

✅ Strict Scope Rule: 2+ = global, 1 = local ✅ Names that scream functionality ✅ Container = same name as feature

Conclusion

With this system you have:

  1. Total Control: You decide, AI executes
  2. 7 Specialized Agents: Each one expert in their area
  3. Real TDD Workflow: Tests → Implementation → Security → A11Y
  4. Clear Architecture: Simple and effective Scope Rule
  5. Concrete User Stories: Like in Jira, with clear criteria

The result is professional, tested, secure and accessible code from day one.

"Sometimes you gotta run before you can walk" - Tony Stark

But with this system, you'll run with guaranteed tests, security and accessibility.

© 2025 - Gentleman Programming
Clean Architecture + AI = Professional Development