Skip to main content
rule CX Codex

gap-analysis — Claude Code rule: map requirements against your codebase

The gap-analysis rule structures the analysis of your existing codebase, identifies what's missing for a feature, and helps you decide whether to extend existing components or build new ones.

MIT ★ 3,774 updated 2026-10-22

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/gap-analysis.md
Open on GitHub

What gap-analysis does

The rule walks through four stages. First, you inventory the current state: key files, components, patterns, and architectural constraints. Next, you list technical needs from your requirements and flag gaps, unknowns, and constraints that conflict with existing design. Then you weigh three approaches: extend existing components (faster to start, but risks bloat), create new ones (clean separation, but more code to maintain), or blend both strategies for complex features.

Your output includes a requirement-to-asset map with gaps tagged, three implementation options with trade-offs, and effort/risk estimates (S for 1–3 days through XL for 2+ weeks). The rule surfaces analysis and options, not a final call — it's a tool for team alignment before design work begins.

What it helps with

  • Identify which existing code and patterns can be reused for a new feature
  • Spot architectural gaps before starting design or implementation
  • Compare options for adding a feature: extend current components or create new ones
  • Estimate effort and risk level based on codebase state and requirements scope
  • Align the team on a development strategy with clear reasoning

Example prompts for the agent

  • Run gap-analysis on a payment processing requirement: what does the codebase have, where are the gaps, which approach fits best
  • Use gap-analysis to decide whether to build a new auth service or extend the existing user module
  • Analyze the gap between your API specification and the current endpoint structure to plan the implementation

How to install gap-analysis

Manually: put the files in place

.claude/rules/gap-analysis.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about gap-analysis

How do I install gap-analysis in Claude Code?

Copy the rule content into .claude/rules/gap-analysis.md at your project root. Claude Code will load it automatically when analyzing your codebase.

What does gap-analysis do?

The rule structures a process to map current codebase assets against requirements, flag what's missing or unknown, and present three options for implementation with effort and risk estimates for each.

How does gap-analysis help me choose between extending or creating new code?

The rule outlines three options. Extend existing components when the feature fits naturally and does not overload them. Create new components when the feature has distinct responsibility or current components are already complex. Use a hybrid approach for features that need both kinds of work.

Source text

gap-analysis.md · MIT
# Gap Analysis Process

## Objective
Analyze the gap between requirements and existing codebase to inform implementation strategy decisions.

## Analysis Framework

### 1. Current State Investigation

- Scan for domain-related assets:
  - Key files/modules and directory layout
  - Reusable components/services/utilities
  - Dominant architecture patterns and constraints

- Extract conventions:
  - Naming, layering, dependency direction
  - Import/export patterns and dependency hotspots
  - Testing placement and approach

- Note integration surfaces:
  - Data models/schemas, API clients, auth mechanisms

### 2. Requirements Feasibility Analysis

- From EARS requirements, list technical needs:
  - Data models, APIs/services, UI/components
  - Business rules/validation
  - Non-functionals: security, performance, scalability, reliability

- Identify gaps and constraints:
  - Missing capabilities in current codebase
  - Unknowns to be researched later (mark as "Research Needed")
  - Constraints from existing architecture and patterns

- Note complexity signals:
  - Simple CRUD / algorithmic logic / workflows / external integrations

### 3. Implementation Approach Options

#### Option A: Extend Existing Components
**When to consider**: Feature fits naturally into existing structure

- **Which files/modules to extend**:
  - Identify specific files requiring changes
  - Assess impact on existing functionality
  - Evaluate backward compatibility concerns

- **Compatibility assessment**:
  - Check if extension respects existing interfaces
  - Verify no breaking changes to consumers
  - Assess test coverage impact

- **Complexity and maintainability**:
  - Evaluate cognitive load of additional functionality
  - Check if single responsibility principle is maintained
  - Assess if file size remains manageable

**Trade-offs**:
- ✅ Minimal new files, faster initial development
- ✅ Leverages existing patterns and infrastructure
- ❌ Risk of bloating existing components
- ❌ May complicate existing logic

#### Option B: Create New Components
**When to consider**: Feature has distinct responsibility or existing components are already complex

- **Rationale for new creation**:
  - Clear separation of concerns justifies new file
  - Existing components are already complex
  - Feature has distinct lifecycle or dependencies

- **Integration points**:
  - How new components connect to existing system
  - APIs or interfaces exposed
  - Dependencies on existing components

- **Responsibility boundaries**:
  - Clear definition of what new component owns
  - Interfaces with existing components
  - Data flow and control flow

**Trade-offs**:
- ✅ Clean separation of concerns
- ✅ Easier to test in isolation
- ✅ Reduces complexity in existing components
- ❌ More files to navigate
- ❌ Requires careful interface design

#### Option C: Hybrid Approach
**When to consider**: Complex features requiring both extension and new creation

- **Combination strategy**:
  - Which parts extend existing components
  - Which parts warrant new components
  - How they interact

- **Phased implementation**:
  - Initial phase: minimal viable changes
  - Subsequent phases: refactoring or new components
  - Migration strategy if needed

- **Risk mitigation**:
  - Incremental rollout approach
  - Feature flags or configuration
  - Rollback strategy

**Trade-offs**:
- ✅ Balanced approach for complex features
- ✅ Allows iterative refinement
- ❌ More complex planning required
- ❌ Potential for inconsistency if not well-coordinated
### 4. Out-of-Scope for Gap Analysis

- Defer deep research activities to the design phase.
- Record unknowns as concise "Research Needed" items only.

### 5. Implementation Complexity & Risk

  - Effort:
    - S (1–3 days): existing patterns, minimal deps, straightforward integration
    - M (3–7 days): some new patterns/integrations, moderate complexity
    - L (1–2 weeks): significant functionality, multiple integrations or workflows
    - XL (2+ weeks): architectural changes, unfamiliar tech, broad impact
  - Risk:
    - High: unknown tech, complex integrations, architectural shifts, unclear perf/security path
    - Medium: new patterns with guidance, manageable integrations, known perf solutions
    - Low: extend established patterns, familiar tech, clear scope, minimal integration

### Output Checklist

- Requirement-to-Asset Map with gaps tagged (Missing / Unknown / Constraint)
- Options A/B/C with short rationale and trade-offs
- Effort (S/M/L/XL) and Risk (High/Medium/Low) with one-line justification each
- Recommendations for design phase:
  - Preferred approach and key decisions
  - Research items to carry forward

## Principles

- **Information over decisions**: Provide analysis and options, not final choices
- **Multiple viable options**: Offer credible alternatives when applicable
- **Explicit gaps and assumptions**: Flag unknowns and constraints clearly
- **Context-aware**: Align with existing patterns and architecture limits
- **Transparent effort and risk**: Justify labels succinctly

© gotalab · MIT · gotalab/cc-sdd

Similar IDE rules

All IDE rules for Code review and refactoring →

From the same set12

The whole set →
requirements-review-gate The requirements-review-gate rule halts work and requires fixing the requirements draft before requirements.md is written. It validates scope coverage, EARS format compliance, and structural quality. CX Codex +1 ★ 3,774repo stars design-review-gate design-review-gate audits draft architectures before generating design.md. It links requirement IDs to concrete components and prevents speculative interfaces. CX Codex +1 ★ 3,774repo stars ears-format The ears-format rule formats acceptance criteria with EARS patterns. Use it when a specification needs clear conditions, subjects, and system responses. CX Codex +1 ★ 3,774repo stars design-discovery-full The design-discovery-full rule systematically maps requirements, existing code, technologies, and risks before design begins. It ensures architectural choices rest on facts rather than assumptions. CX Codex +1 ★ 3,774repo stars design-review design-review reviews technical design documents before coding starts and issues a GO/NO-GO verdict. Caps feedback at three critical issues tied directly to project requirements. CX Codex +1 ★ 3,774repo stars cc-sdd-new-agent The cc-sdd-new-agent skill guides a new coding-agent integration in cc-sdd, from official-format research and planning to implementation checks. CX Codex +1 ★ 3,774repo stars tasks-generation tasks-generation guides AI coding agents to generate structured, dependency-ordered technical task plans from specifications without leaking low-level code details. CX Codex +1 ★ 3,774repo stars design-principles The design-principles rule sets checks for architecture, types, documentation, and Mermaid diagrams. Use it when drafting design.md or reviewing component boundaries. CX Codex +1 ★ 3,774repo stars

Project sponsors

Companies that keep this analytics open