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
.claude/rules/gap-analysis.mdWhat 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/gap-analysis.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/gap-analysis.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/gap-analysis.mdManually: put the files in place
.clinerules/gap-analysis.mdStep 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