Codebase Navigator
Use this skill FIRST when exploring code, finding files, or understanding project structure.
Quick Start
Search scripts (preferred)
Run the bundled scripts for common searches:
# Find functions/methods
.agents/skills/codebase-navigator/scripts/search.sh functions <pattern>
# Find React components
.agents/skills/codebase-navigator/scripts/search.sh components <pattern>
# Find API endpoints
.agents/skills/codebase-navigator/scripts/search.sh endpoints
# Trace an API flow end-to-end
.agents/skills/codebase-navigator/scripts/trace.sh api-flow <endpoint>
# Trace a data field from backend to UI
.agents/skills/codebase-navigator/scripts/trace.sh data-flow <field_name>
# Find component hierarchy
.agents/skills/codebase-navigator/scripts/trace.sh component-tree <ComponentName>Direct ripgrep patterns
# Find any symbol
rg --no-heading -n '\bMySymbol\b' apps/
# Python function definitions
rg --no-heading -n '(def|async def) my_function' apps/backend/ --type py
# React component usage
rg --no-heading -n '<MyComponent' apps/frontend/ --glob '*.tsx'
# Pydantic models
rg --no-heading -n 'class My.*BaseModel' apps/backend/ --type py
# API route handlers
rg --no-heading -n '@(router|app)\.(get|post|put|patch|delete)' apps/backend/ --type pyArchitecture Overview
| Need | Document |
|---|---|
| Backend architecture | docs/agent/architecture/backend-architecture.md |
| Frontend architecture | docs/agent/architecture/frontend-architecture.md |
| API contracts | docs/agent/apis/front-end-apis.md |
| API flow maps | docs/agent/apis/api-flow-maps.md |
| Full doc index | docs/agent/README.md |
Project Layout
apps/
├── backend/app/
│ ├── main.py # FastAPI entry, CORS, routers
│ ├── config.py # Pydantic settings from env
│ ├── database.py # TinyDB wrapper
│ ├── llm.py # LiteLLM wrapper
│ ├── routers/ # API endpoints
│ ├── services/ # Business logic
│ ├── schemas/ # Pydantic models
│ └── prompts/ # LLM prompt templates
│
└── frontend/
├── app/ # Next.js pages
├── components/ # UI components
├── lib/ # API client, utilities, i18n
├── hooks/ # Custom React hooks
└── messages/ # i18n translations (en, es, zh, ja)Common Workflows
"Where is X defined?"
.agents/skills/codebase-navigator/scripts/search.sh functions my_function
.agents/skills/codebase-navigator/scripts/search.sh components MyComponent
.agents/skills/codebase-navigator/scripts/search.sh classes MyClass
.agents/skills/codebase-navigator/scripts/search.sh types MyType"What calls X?"
.agents/skills/codebase-navigator/scripts/search.sh usage my_function
.agents/skills/codebase-navigator/scripts/search.sh deps my_file.py"How does data flow for feature X?"
.agents/skills/codebase-navigator/scripts/trace.sh api-flow resumes
.agents/skills/codebase-navigator/scripts/trace.sh data-flow personalInfo
.agents/skills/codebase-navigator/scripts/trace.sh component-tree ResumeEditorKey Entry Points
| What | File |
|---|---|
| Backend startup | apps/backend/app/main.py |
| Frontend pages | apps/frontend/app/ |
| API client | apps/frontend/lib/api.ts or lib/api-client.ts |
| Design tokens | apps/frontend/app/globals.css |
| Resume schemas | apps/backend/app/schemas/ |
| LLM prompts | apps/backend/app/prompts/ |
Reference
See references/REFERENCE.md for the full ripgrep cheat sheet and advanced search patterns.