Internal Docs & Codebase Search

Code search ≠ doc search

Your codebase has different retrieval needs than your wiki:

Property	Docs/wiki	Code
Structure	Headings, paragraphs	Functions, classes, imports
Queries	"How do I configure X?"	"Where is X implemented?"
Exact match matters	Sometimes	Always (function names, types)
Freshness	Weekly/monthly	Every commit
Optimal chunk unit	Section/paragraph	Function or class

Treating code like prose produces RAG that retrieves the wrong file confidently.

Code-aware indexing strategies

1. AST-based chunking Parse source into functions/classes. Each chunk = one symbol with its signature, body, and docstring. Preserves semantic boundaries.

2. File-level with metadata Index whole files but tag with: language, path, last commit, test coverage. Filter by directory before semantic search.

3. Graph-enhanced retrieval Build a dependency graph (imports, calls). When retrieving processPayment, also pull its callers, callees, and interface definition.

4. Cursor codebase indexing Cursor indexes your repo automatically for @-codebase and agent context. Understand what it indexes (respects .cursorignore) and what it doesn't (external deps, runtime state).

Hybrid search for code

Code queries often mix semantic and exact intent:

"How does auth middleware validate JWT?" → Semantic: auth, middleware, validate → Exact: JWT, validateToken(), jsonwebtoken "Error in PaymentService.processRefund line 142" → Exact: PaymentService, processRefund → Semantic: (less relevant)

Production pattern: BM25 for symbol names + vector for conceptual queries, merged with reranking.

Internal docs that RAG can actually use

Not all internal docs are RAG-ready:

Doc type	RAG quality	Improvement
Markdown ADRs	High	Keep current; date-stamp decisions
Runbooks	High if structured	Add "symptom → diagnosis → fix" format
Confluence/wiki	Medium	Export clean markdown; strip navigation junk
Slack threads	Low	Summarize decisions into ADRs instead
Code comments	Medium	Don't rely on comments over types/tests
API specs (OpenAPI)	High	Auto-ingest from spec files

Maintenance is the hard part. Stale RAG is worse than no RAG — it generates confident answers from deleted APIs.

Building a codebase Q&A eval set

Before tuning retrieval, build ground truth:

Run 20–50 queries. Measure: recall@3 (right file in top 3), answer accuracy (human-rated). Iterate on chunking and search before switching embedding models.

Cursor-specific patterns

For day-to-day work (not building a RAG product):

• @-codebase — semantic search over indexed repo; good for "where is X?"
• @-file / @-folder — explicit context when you know the location
• @-docs — external documentation (framework APIs)
• Rules + indexing — rules tell the agent conventions; indexing finds the code

Don't fight the index. If @-codebase misses, your indexing scope or chunking needs work — or the code isn't where you think it is.

Production RAG for eng teams

If building internal tooling (not just using Cursor):

Git push → Webhook → Parse changed files → Re-chunk → Re-embed → Update index ↓ User query → Hybrid search → Rerank → Inject top-k → LLM → Cite sources

Key ops concerns: index freshness (SLA: <5 min after merge), access control (respect repo permissions), cost (re-embed only changed files), and eval regression on index updates.

Interview framing

"For codebase search, I'd use AST-aware chunking with hybrid search — BM25 for symbol names, vectors for conceptual queries. I'd maintain an eval set of real engineer questions and measure recall before tuning embeddings. Index freshness on every merge is non-negotiable."

Senior signal: Distinguish IDE indexing (Cursor @-codebase) from production RAG (vector DB + CI pipeline). Explain why Slack threads make bad RAG sources. Mention access control for multi-repo indexes.