Skip to content

codebase-onboarding.md

Latest commit

 

History

History
187 lines (144 loc) · 5.08 KB

codebase-onboarding.md

File metadata and controls

187 lines (144 loc) · 5.08 KB
Raw
description Step-by-step workflow for indexing a new repository and validating search results
alwaysApply false

Codebase Onboarding

Step-by-step guide for indexing a repository and validating the results.

When to Apply

Use this workflow when:

  • A user asks to "index this repo" or "make this codebase searchable"
  • Starting work on a new repository that hasn't been indexed yet
  • Re-indexing after major refactoring or branch switches

Prerequisites

  1. Solr must be running (compass_setup { "action": "check" })
  2. The repository must be checked out locally with an absolute path available
  3. Sufficient disk space for the Solr index (roughly 2-5x the source size for chunked content)

Step-by-Step Onboarding

1. Verify Environment

compass_setup { "action": "check" }

If Solr is not running, offer to initialize it. Wait for confirmation before pulling Docker images.

2. Check Current Index Status

compass_status {}

Review:

  • Whether this repository root is already indexed
  • Total document count in the codebase collection
  • Embedding provider consistency (no providerMismatch)

3. Analyze the Repository Structure

Before indexing, understand what you're indexing:

  • Identify the primary language(s) and framework(s)
  • Note any monorepo structure (multiple packages/services)
  • Check for large generated files, vendor directories, or binary assets that should be excluded

4. Index the Repository

Standard indexing (recommended for most repos):

compass_index_folder {
  "path": "/absolute/path/to/repository",
  "chunked": true
}

For monorepos — index each service separately:

compass_index_folder {
  "path": "/absolute/path/to/monorepo/services/api",
  "chunked": true
}
compass_index_folder {
  "path": "/absolute/path/to/monorepo/services/web",
  "chunked": true
}

With custom exclusions (when defaults aren't sufficient):

compass_index_folder {
  "path": "/absolute/path/to/repository",
  "chunked": true,
  "exclude": ["*.generated.ts", "migrations/**", "fixtures/**"]
}

With file size limit (for repos with large data files):

compass_index_folder {
  "path": "/absolute/path/to/repository",
  "chunked": true,
  "maxFileSize": 50000
}

5. Validate the Index

After indexing completes, verify with representative queries:

Test 1 — Known location:

compass_search_codebase {
  "query": "main entry point or application bootstrap",
  "root": "/absolute/path/to/repository",
  "mode": "hybrid",
  "topK": 5
}

Test 2 — Conceptual search:

compass_search_codebase {
  "query": "error handling and exception management",
  "root": "/absolute/path/to/repository",
  "mode": "vector",
  "topK": 5
}

Test 3 — Keyword precision:

compass_search_codebase {
  "query": "handleRequest",
  "root": "/absolute/path/to/repository",
  "mode": "keyword",
  "topK": 5
}

6. Store Onboarding Context

After successful indexing, store a memory note for future sessions:

compass_remember {
  "note": "Repository /path/to/repo is indexed in Solr Compass. Primary language: TypeScript. Framework: Express. Last indexed: 2026-08-07.",
  "category": "context",
  "tags": ["repo-name", "indexed"]
}

7. Incremental Updates

After making changes to the codebase, synchronize the index:

compass_reindex_folder {
  "path": "/absolute/path/to/repository"
}

This performs incremental sync — only changed files are re-embedded and updated.

Default Exclusions

The indexer automatically excludes:

  • node_modules/, vendor/, .venv/, __pycache__/
  • .git/, .svn/, .hg/
  • dist/, build/, out/, .next/
  • Lock files (package-lock.json, yarn.lock, bun.lockb, etc.)
  • Binary files and images

Override with include or exclude parameters only when the defaults don't fit.

Chunking Strategy

  • Chunked mode (chunked: true) — Splits files into overlapping segments for better semantic matching. Recommended for most codebases.
  • Whole-file mode (chunked: false) — Indexes entire files as single documents. Use only for small files or when you need file-level granularity.

The local embedding provider has a 512-token input ceiling. Chunks exceeding this are truncated. For large functions or classes, chunked mode ensures all parts are searchable.

Isolated Collections

For hard separation between projects:

compass_setup { "action": "create_collection", "name": "codebase-project-alpha" }
compass_index_folder {
  "path": "/path/to/project-alpha",
  "collection": "codebase-project-alpha",
  "chunked": true
}

Troubleshooting Indexing

Symptom Cause Fix
Indexing times out Repository too large for single pass Index subdirectories separately
Missing files in results File excluded by default patterns Use explicit include pattern
Low relevance scores Chunks too large for local embedder Ensure chunked: true, reduce maxFileSize
providerMismatch warning Switched embedding providers Full reindex: compass_reindex_folder { "path": "...", "force": true }