Codebase Research

NO NEW CODE WITHOUT UNDERSTANDING THE EXISTING CODE FIRST

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"];
}

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 patterns

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.

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.