# Codebase Understanding

> Navigate the codebase cheaply by reading the context store first, not re-scanning the repo. Use at the start of any investigation, feature, or review to locate the relevant service/file fast and with minimal tokens. Triggers on "where is", "how does X work", "understand the code", "find the service for".

- Skill: `onedro1d/codebase-understanding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add onedro1d/codebase-understanding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedro1d/codebase-understanding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OneDro1d (https://skillmd.com/u/onedro1d)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/onedro1d/codebase-understanding

---


# Codebase Understanding (read-first, low-token)

Goal: locate the relevant code in the fewest tokens. NEVER scan the whole repo to answer a question the context store already answers.

## Order of reading (stop as soon as you have what you need)
1. `.claude/context/SERVICE-MAP.md` — which service/db/queue/API owns this area.
2. `.claude/context/FINDINGS.md` — is this already known/solved?
3. `.claude/context/DECISIONS.md` — is the current behavior intentional?
4. The ONE relevant `<service>/CLAUDE.md` — contracts, key files, gotchas.
5. The shared-models `CLAUDE.md` — only when tracing a routing key / RPC across services.
6. Source — targeted, by `file:line` from the above, via Grep/Read. Not whole-file dumps unless necessary.

## Cheap search patterns
- Routing key / RPC: `grep -rn "<routing.key>" <service>/` then open the dispatcher.
- A symbol: `grep -rn "MethodName\|TypeName" <service>/ --exclude-dir={obj,bin}`.
- A flow: start at the SERVICE-MAP "In → Out" column, follow the routing key to the next consumer.

## Output
A short "where it lives" answer: service, file:line, and the one-line role. Do not paste large code blocks — cite locations.

## Don't
- Don't re-derive the architecture; it's in SERVICE-MAP/CLAUDE.md.
- Don't read every service. Read the one(s) the map points to.