Codebase Research
Overview
Before writing new code in an existing project, understand what already exists inside it. The codebase itself is the most authoritative reference for how things should be built. Every project accumulates conventions, patterns, and implicit standards that new code must respect.
Core principle: Search the current codebase before coding. Find similar files, functions, and patterns. Match existing conventions exactly. Never introduce a second way of doing something when a first way already exists.
No exceptions. No workarounds. No shortcuts.
The Prime Directive
NO NEW CODE WITHOUT UNDERSTANDING THE EXISTING CODE FIRSTIf you have not searched the current codebase for prior implementations of the same pattern, you are risking inconsistency. Found nothing similar? Document what you searched. Then build, establishing the convention deliberately.
No excuses:
- Do not "just start coding and check conventions later"
- Do not assume your preferred pattern is the project's pattern
- Do not introduce new libraries when the project already uses an equivalent
- Do not create a new file structure that contradicts the existing one
- "I know the best way to do this" is irrelevant if the project already does it a different way consistently
When to Use
Mandatory when:
- Adding a new feature to an existing codebase
- Creating a new file, component, module, or service
- Implementing a pattern that likely exists elsewhere in the project
- Writing tests for existing functionality
- Adding error handling, logging, or validation logic
Particularly valuable when:
- The project has established architectural patterns (MVC, hexagonal, etc.)
- There are existing files similar to what you need to create
- The codebase has custom utilities, helpers, or shared modules
- The project uses specific naming conventions or code organization rules
- There are existing tests that demonstrate the expected testing approach
The Entry Protocol
digraph codebase_research_gate {
rankdir=TB;
start [label="Task: Write new code\nin existing project", shape=doublecircle];
search [label="SEARCH\ncurrent codebase for\nsimilar implementations", shape=box];
found [label="Similar patterns found?", shape=diamond];
analyze [label="ANALYZE\nConventions, structure,\nnaming, error handling", shape=box];
template [label="Use as template?\n(follow the pattern)", shape=diamond];
follow [label="FOLLOW\nMatch the existing pattern\nexactly", shape=box style=filled fillcolor=lightgreen];
adapt [label="ADAPT\nUse the convention\nwith modifications", shape=box style=filled fillcolor=lightyellow];
establish [label="ESTABLISH\nNo precedent exists;\ncreate a deliberate\nnew convention", shape=box];
document [label="Document search results\nand decision rationale", shape=box];
start -> search;
search -> found;
found -> analyze [label="yes"];
found -> document [label="no"];
document -> establish;
analyze -> template;
template -> follow [label="yes - close match"];
template -> adapt [label="partially - same idea\ndifferent details"];
}BEFORE writing new code in an existing project:
- SEARCH -- Query the codebase for similar files, functions, patterns, and conventions
- ANALYZE -- Study how existing code handles the same concerns
- MATCH -- Align your new code with established conventions
- ONLY THEN -- Begin writing
Search Methodology
What to Search For
When about to create something new, search the codebase for each of these:
| Search Target | Why | How |
|---|---|---|
| Similar files | Find the template to follow | Glob for files with similar names or in similar directories |
| Similar functions | Match function signatures and patterns | Grep for functions that do analogous work |
| Imports and dependencies | Use what the project already uses | Grep for import statements to find established libraries |
| Error handling | Match the project's error patterns | Grep for try/catch, Result types, error classes |
| Naming conventions | Use the same casing and terminology | Read adjacent files, check for camelCase vs snake_case vs kebab-case |
| File organization | Place new files where they belong | List directory structures, find where similar code lives |
| Test patterns | Write tests the way the project writes tests | Find test files for similar modules, match their structure |
| Configuration patterns | Match config approaches | Search for.env usage, config files, constants |
Search Techniques
Structured search sequence -- Follow this order for thorough coverage:
1. DIRECTORY SCAN: List files in the relevant directories
-> Understand the project's file organization
2. SIMILAR FILE SEARCH: Glob for files with similar names or purposes
-> Find the closest existing template for what you need to build
3. PATTERN GREP: Search for specific patterns you plan to use
-> Confirm the project's approach to that pattern
4. IMPORT ANALYSIS: Check what libraries and utilities are already imported
-> Use existing dependencies rather than introducing new ones
5. TEST FILE REVIEW: Find tests for similar functionality
-> Match the testing approach, assertion style, and setup patternsMinimum threshold before writing new code: Review at least 2 similar files in the codebase.
Convention Matching
The Consistency Principle
When the codebase does something one way, you do it the same way. Personal preference is irrelevant. Project consistency outweighs individual opinion.
| Dimension | Match Exactly |
|---|---|
| Naming | Variable names, function names, file names, class names |
| Structure | File layout, directory organization, module boundaries |
| Patterns | How the project handles state, errors, async, validation |
| Style | Formatting, comment style, documentation approach |
| Dependencies | Use the project's existing libraries, not alternatives |
| Testing | Test framework, assertion library, setup/teardown approach |
| Error handling | Throw vs return, error types, error messages |
Common Convention Signals
LOOK FOR these indicators of established conventions:
- Linter/formatter config (.eslintrc, .prettierrc, rustfmt.toml, etc.)
-> These are explicit rules. Follow them exactly.
- Shared utility files (utils/, helpers/, lib/, common/)
-> These are the project's building blocks. Use them.
- Base classes or interfaces (BaseController, AbstractService)
-> These define the inheritance/composition pattern. Extend them.
- Barrel files (index.ts, __init__.py, mod.rs)
-> These define the export pattern. Add to them.
- Test helpers (test/helpers/, fixtures/, factories/)
-> These are the testing infrastructure. Build on them.Analysis Checklist
When you find similar code in the codebase, extract answers to these questions:
1. FILE PLACEMENT: Where does this type of file live?
-> Same directory? Nested by feature? Grouped by type?
2. FILE NAMING: What naming pattern does the file follow?
-> ComponentName.tsx? component-name.ts? component_name.py?
3. EXPORTS: How are things exported?
-> Default export? Named exports? Re-exported from barrel?
4. FUNCTION SIGNATURES: What do similar function signatures look like?
-> Parameter ordering, return types, async vs sync
5. ERROR HANDLING: How does this part of the codebase handle errors?
-> Try/catch? Result types? Error callbacks? Thrown exceptions?
6. LOGGING: Does the project have a logging pattern?
-> Logger instance? Console methods? Structured logging?
7. VALIDATION: How does the project validate input?
-> Zod? Joi? Manual checks? Type guards?
8. STATE MANAGEMENT: How is state handled?
-> Redux? Zustand? Context? Signals? Local state?
9. TESTING APPROACH: What do tests for similar code look like?
-> Unit tests? Integration? What assertion library?
10. DOCUMENTATION: Are there JSDoc comments, docstrings, or inline docs?
-> Match the existing documentation density and style.When No Precedent Exists
Sometimes you are genuinely building something the codebase has never done before. In that case:
- Confirm absence -- Search at least 3 different ways to be sure no precedent exists
- Check adjacent projects -- If this is a monorepo, check sibling packages
- Consult external sources -- Use godmode:github-search to find patterns from public repositories
- Establish deliberately -- When creating a new convention, make it consistent with the spirit of the existing codebase
- Document the decision -- Note why a new pattern was introduced
Integration with Other Skills
During Intent Discovery
When godmode:intent-discovery is exploring the project landscape:
- Search the codebase for existing implementations related to the proposed feature
- Report conventions that the new feature must follow
- Identify reusable code -- utilities, components, and services that already solve part of the problem
During Implementation
When writing code after design approval:
- Find the template file -- the closest existing file to what you need to create
- Copy the structure -- match the template's organization exactly
- Swap the specifics -- replace domain details while preserving the pattern
- Verify consistency -- compare your new file against the template to catch deviations
Cognitive Traps
| Rationalization | Truth |
|---|---|
| "My approach is cleaner than what the project uses" | Consistency across a project is worth more than local perfection. Two patterns are worse than one adequate pattern. |
| "I will refactor the existing code to match my style" | Refactoring is a separate task. Match the existing style now. Propose a refactor later if warranted. |
| "The project does not have a pattern for this" | Did you search thoroughly? Check 3+ similar files. If truly no precedent, establish one deliberately. |
| "I do not need to check -- this is a new module" | New modules still live inside the existing project. They must respect its conventions. |
| "The existing pattern is outdated" | Outdated but consistent is better than modern but inconsistent. Propose a migration, do not create a fork. |
| "Checking conventions slows me down" | Writing code that fails review or introduces inconsistency slows you down more. |
| "It is just a small utility function" | Small utilities are the most reused code. Getting their pattern wrong affects everything that depends on them. |
Guardrails
Prohibited actions:
- Writing new code without searching the codebase for similar implementations
- Introducing a new library when the project already uses an equivalent
- Creating a file structure that contradicts the existing organization
- Using a naming convention different from the project's established one
- Skipping test pattern matching ("I will write tests my way")
Required actions:
- Search the codebase for at least 2 similar files before writing new code
- Match the naming conventions of the surrounding code exactly
- Use existing shared utilities and helpers instead of creating duplicates
- Follow the established testing patterns for the project
- Document your findings when no precedent exists in the codebase
Quick Reference
SEARCH -> ANALYZE -> MATCH -> BUILD
Search: Find 2+ similar files, grep for patterns, check imports
Analyze: Extract conventions for naming, structure, error handling, testing
Match: Align your new code with every convention you found
Build: Write code that looks like it belongs in the projectIntegration
Invoked during:
- godmode:intent-discovery -- Search codebase during "Survey project landscape" phase
- godmode:reference-engine -- Routed here for internal code pattern research
- godmode:task-planning -- Verify conventions before each implementation task
- godmode:quality-enforcement -- Consistency checks against codebase patterns
Complementary skills:
- godmode:github-search -- For searching EXTERNAL repositories, GitHub, and package registries for open-source implementations, libraries, and patterns to study or adopt
- godmode:pattern-matching -- Deeper pattern analysis within the codebase
- godmode:specification-first -- Feeds codebase conventions into formal specifications
- godmode:project-bootstrap -- When starting a new project (no existing codebase to research)