Codebase Pattern Strategist

A specialist agent that finds and documents existing code patterns in your codebase, providing examples and templates that serve as implementation guides for new features — strictly documenting what exists without suggesting improvements.

When to Use This Agent

Choose Codebase Pattern Strategist when:

• Starting a new feature and need to match existing project conventions
• Onboarding new team members who need to understand project patterns
• Creating a pattern catalog to ensure consistency across the team
• Finding how similar functionality is already implemented in the codebase
• Generating boilerplate for a new module that follows established patterns

Consider alternatives when:

• Wanting to improve or refactor existing patterns (use a code simplifier agent)
• Looking for industry best practices rather than project-specific patterns (use a general knowledge agent)
• Debugging existing implementations (use a debugging agent)

Quick Start

Copy
# .claude/agents/codebase-pattern-strategist.yml
name: Codebase Pattern Strategist
description: Find and document existing codebase patterns
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep

Example invocation:

claude "Find the pattern used for API route handlers in this codebase and show me 3 examples I can follow when creating a new endpoint"

Core Concepts

Pattern Discovery Workflow

Step	Action	Output
1. Identify	User describes what they want to build	Pattern search scope
2. Scan	Search for similar implementations	Candidate file list
3. Extract	Read and analyze matching files	Pattern structure
4. Document	Present the pattern with examples	Template + examples
5. Generate	Create boilerplate following the pattern	Ready-to-use code

Pattern Documentation Format

Copy
## Pattern: API Route Handler

### Structure
Every API route in this project follows this structure:
1. Zod schema validation at the top of the file
2. Authentication middleware applied via wrapper
3. Try/catch with standardized error responses
4. Service layer delegation for business logic

### Example 1: src/app/api/users/route.ts
```typescript
import { z } from 'zod';
import { withAuth } from '@/lib/auth';
import { userService } from '@/services/userService';

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

export const POST = withAuth(async (req, { user }) => {
  const body = createUserSchema.parse(await req.json());
  const newUser = await userService.create(body);
  return Response.json(newUser, { status: 201 });
});

Example 2: src/app/api/products/route.ts

[Similar structure with product-specific schema]

Template for New Route

Copy
import { z } from 'zod';
import { withAuth } from '@/lib/auth';
import { ${resource}Service } from '@/services/${resource}Service';

const create${Resource}Schema = z.object({
  // Define your fields here
});

export const POST = withAuth(async (req, { user }) => {
  const body = create${Resource}Schema.parse(await req.json());
  const result = await ${resource}Service.create(body);
  return Response.json(result, { status: 201 });
});

Conventions Observed

• File location: src/app/api/${resource}/route.ts
• Schema naming: ${action}${Resource}Schema
• Service naming: ${resource}Service.${action}()
• Error format: { error: string, details?: unknown }

## Configuration

| Parameter | Description | Default |
|-----------|-------------|---------|
| `pattern_scope` | Where to search for patterns (directory, project) | `project` |
| `example_count` | Number of examples to show per pattern | `3` |
| `include_template` | Generate a reusable template from the pattern | `true` |
| `include_conventions` | List observed naming/structure conventions | `true` |
| `output_format` | Output format (markdown, json) | `markdown` |
| `ignore_tests` | Exclude test files from pattern search | `false` |

## Best Practices

1. **Show patterns exactly as they exist, without editorial commentary.** The agent's job is to mirror what the codebase does, not to judge it. If the project uses callbacks instead of promises, document the callback pattern faithfully. If error handling is inconsistent, show the most common variant and note the variations. Developers following these patterns need accuracy, not opinions about what they should change.

2. **Provide at least three examples per pattern to demonstrate consistency.** One example might be an outlier. Two examples might be coincidence. Three examples confirm a pattern. Select examples that show the pattern applied to different entities (users, products, orders) so developers can generalize the structure. Highlight which parts are constant (boilerplate) and which parts vary (entity-specific logic).

3. **Include the full file context, not just the pattern snippet.** Show imports, type definitions, and surrounding code. Developers creating new files need to know what to import, how to export, and what adjacent code expects. A pattern snippet without context forces developers to hunt for the missing pieces, defeating the purpose of pattern documentation.

4. **Organize patterns by developer workflow, not by code structure.** Group patterns by what developers need to build: "Adding a new API endpoint," "Creating a new database table," "Adding a new React page." Each group includes the route handler pattern, the service layer pattern, the database migration pattern, and the test file pattern — everything needed to complete the workflow in one place.

5. **Detect and document inconsistencies rather than hiding them.** If the codebase has two different patterns for the same thing (some routes use middleware auth, others use in-handler auth), document both with a note like "Two patterns observed — 18 routes use middleware auth, 4 routes use in-handler auth." This helps developers choose the dominant pattern and alerts the team to inconsistencies worth resolving.

## Common Issues

**Pattern search returns too many false positives.** Searching for "how are services structured" might match every file containing the word "service." Narrow pattern searches by combining structural cues: file location (src/services/*.ts), naming conventions (export class *Service), and import patterns (imports from specific modules). Multi-signal matching produces more precise results than keyword searches.

**Extracted patterns are too specific to one entity to generalize.** If the pattern example is deeply tied to user-specific logic, it is hard to adapt for products or orders. Select the simplest entity implementation as the primary example — the one with the least domain-specific complexity. Use that as the template base, then show a more complex example as a secondary reference for edge cases.

**Patterns have evolved over time and older code follows different conventions.** Codebases often have multiple generations of patterns. Identify the most recent pattern by checking file modification dates and recent PR history. Present the current pattern as the primary template, and note older patterns with a label like "Legacy pattern (pre-2025) — seen in 12 files, current pattern preferred for new code."