Agentic Development Patterns

// Conceptual model of the agentic loop
interface AgentState {
  task: string;
  plan: Step[];
  currentStep: number;
  observations: string[];
  filesModified: string[];
  testsPass: boolean;
}

// What happens inside Claude Code on each task:
async function agenticLoop(task: string): Promise<Result> {
  // 1. PLAN: Understand the task and create a plan
  const context = await readRelevantFiles(task);
  const plan = await createPlan(task, context);

  for (const step of plan.steps) {
    // 2. EXECUTE: Perform the action
    const result = await executeStep(step);

    // 3. OBSERVE: Check the result
    const observation = await observe(result);

    // 4. ITERATE: Adjust if needed
    if (observation.hasError) {
      const fix = await diagnoseAndFix(observation.error);
      await executeStep(fix);
    }
  }

  // Final verification
  const tests = await runTests();
  if (!tests.pass) {
    await fixFailingTests(tests.failures);
  }

  return { success: true, filesModified: plan.filesModified };
}

# Breakpoint pattern in practice
> /plan
> I need to migrate our authentication from custom JWT implementation
  to NextAuth.js. This is security-critical code. Plan every step
  but do NOT execute anything yet.

# Claude produces a detailed plan:
# 1. Install next-auth and @auth/prisma-adapter
# 2. Create app/api/auth/[...nextauth]/route.ts
# 3. Update prisma schema with Account, Session, User tables
# 4. Migrate existing user data
# 5. Update all protected routes to use getServerSession
# 6. Remove old JWT middleware
# 7. Update login/signup pages
# 8. Add tests

# You review the plan carefully, then:
> Good plan. Two changes:
  - For step 4, create a migration script but do NOT run it automatically.
    I want to review the SQL first.
  - Skip step 6 for now. Let the old middleware co-exist until we verify
    everything works.
  Now execute the modified plan.

# Terminal 1: Feature implementation
cd ~/project
claude "Add the notification preferences page. Follow the pattern
  in app/settings/profile/page.tsx for layout and form handling."

# Terminal 2: Test writing (in parallel)
cd ~/project
claude "Write comprehensive tests for app/lib/billing.ts. Cover
  all exported functions, edge cases, and error scenarios."

# Terminal 3: Documentation (in parallel)
cd ~/project
claude "Update the API documentation in docs/api.md to reflect
  the new endpoints added this week. Check the git log for recent
  changes to app/api/"

# All three agents work simultaneously, dramatically increasing throughput

# Start a background agent for a long-running task
claude --background "Migrate all 47 JavaScript files in app/legacy/
  to TypeScript. For each file:
  1. Rename .js to .ts/.tsx
  2. Add proper type annotations
  3. Fix any type errors
  4. Run the type checker after each file
  Create a summary of all changes when done."

# Claude runs in the background. You get notified when done.
# Meanwhile, you work on other things.

# Check on background agent status
claude --status

# The verification workflow
# After Claude completes a task:

# 1. Review the diff
> Show me a summary of everything you changed, organized by file.

# 2. Check for common issues
> Are there any files where you used patterns that differ from the
  rest of the codebase? Any potential security concerns?

# 3. Run tests
> Run the full test suite and show me the results.

# 4. Manual spot-check
# Open the most critical changed files in your editor
# Read the logic carefully for the business-critical parts
# AI is great at syntax but can miss domain-specific logic errors

// Principles for agent-friendly codebases:

// 1. CLEAR BOUNDARIES - Each file has one responsibility
// Bad: utils.ts with 50 unrelated functions
// Good: dateUtils.ts, formatUtils.ts, validationUtils.ts

// 2. CONSISTENT PATTERNS - Same structure everywhere
// If all API routes follow the same pattern, Claude learns it once
// and applies it correctly everywhere

// 3. TYPE SAFETY - Types are documentation for the AI
// Claude uses TypeScript types to understand data shapes
// The more precise your types, the better the output
interface User {
  id: string;
  email: string;
  role: "admin" | "editor" | "viewer"; // Discriminated unions help
  createdAt: Date;
  preferences: UserPreferences; // Named types over inline objects
}

// 4. TESTS AS SPECIFICATION - Tests tell the agent what correct means
// When Claude can run tests, it can verify its own changes
// Projects with good test coverage get dramatically better agentic results

// 5. DOCUMENTED CONSTRAINTS - In CLAUDE.md or inline comments
// If a function has a non-obvious constraint, document it
// "This must be called before initializeDatabase()" etc.