Best Practices — Codebase Context Skill

1. Context-First Workflow

The single most important habit is to let CCS build context before you start working. Resist the urge to explore manually — the index is faster and more accurate.

Always run /ccs-init before starting work on any project — this generates the full context map that powers every other command
Run /ccs-query before any fix or build to preview which files would be selected for your task
Trust the index — don't explore manually when CCS has already mapped the codebase and its dependency graph
Run /ccs-refresh after major changes (not after every edit) — the index stays accurate for routine edits

2. Token Efficiency

CCS exists to reduce token waste. Every query that reads the index instead of exploring the filesystem saves significant cost and latency.

~70-90% token savings per query — CCS reads compact index files instead of scanning entire directories
Use /ccs-status to check your current token savings estimate and index health
Right model for the job — small models (Haiku) for scanning, medium (Sonnet) for coding, large (Opus) for deep reasoning
Never explore what's already indexed — read .ccs/file-index.md first instead of using Glob/Grep blindly

3. Branch Hygiene

Branch-aware context means you never lose your place when switching between features. Each branch carries its own context reference.

Use /ccs-branch for every feature — creates a context reference file tied to the branch
Branch refs replace codebase re-scanning when switching contexts between features
Run /ccs-diff before merging to understand the full blast radius of your changes
Use /ccs-pr to generate structured PR descriptions with dependency analysis and test coverage

4. Git Workflow Pipeline

The recommended end-to-end flow for any feature, from branch creation to merge:

Recommended Flow: Branch → Build → Test → PR → Merge

        # Step 1: Create branch with context

        $ /ccs-branch create feature-x

        # Step 2: Build with tracked context

        $ /ccs-build "implement feature"

        # Step 3: Run tests, auto-fix failures

        $ /ccs-test

        # Step 4: Generate PR with blast radius analysis

        $ /ccs-pr main

        # Step 5: Merge with dependency checking

        $ /ccs-merge feature-x

/ccs-branch create feature-x — Creates the branch and a context reference file so CCS knows what you're working on
/ccs-build "implement feature" — Builds with full tracked context, logging every change to task.md
/ccs-test — Runs your test suite, diagnoses failures, and can auto-fix them with --fix
/ccs-pr main — Generates a structured PR description with blast radius analysis
/ccs-merge feature-x — Merges with dependency checking to catch integration issues

5. Model Selection Guide

Each command is assigned to the optimal model for its task type. This is handled automatically — you don't need to configure anything.

Model	Task Type	Commands
Haiku 4.5	Fast lookups, low token cost	status, query, refresh, track, stash, log
Sonnet 4.6	Coding execution, medium cost	build, fix, test, branch, sync
Opus 4.6	Deep reasoning, highest quality	init, plan, refactor, audit, review, research, deploy, pr, merge, diff

The principle: use the smallest model that can do the job well. Scanning an index doesn't need Opus. Planning an architecture refactor doesn't benefit from Haiku.

6. OS-Specific Setup

macOS / Linux

Terminal (bash / zsh)

        $ npx codebase-context-skill init

        # Git is typically pre-installed on macOS and most Linux distros

        # Works with bash, zsh, and fish shells

Windows

PowerShell / Git Bash

        > npx codebase-context-skill init

        # Works with PowerShell and Git Bash

        # If git is not installed:

        > winget install Git.Git

Linux (no Node.js)

Terminal

        # Install via curl (no npm needed)

        $ curl -fsSL https://contextcode.thinqmesh.com/install.sh | bash

        # Install git if needed

        $ sudo apt install git   # Debian / Ubuntu

        $ sudo dnf install git   # Fedora

7. Multi-Client Compatibility

CCS generates standard markdown files and exposes tools via MCP. This means its context architecture works across multiple AI coding tools.

Client	Integration	Details
Claude Code	Full native support	All 22 slash commands available directly
Codex CLI	Context files as reference	Feed `.ccs/` files as context to any query
ChatGPT	WebMCP connection	Connect via WebMCP at contextcode.thinqmesh.com for tool access
Cursor / VS Code	Context documents	Copy `.ccs/` files as context documents in your editor

8. Session Management

CCS maintains persistent state across your entire session. Here's how to make the most of it.

Start every session with /ccs-status to check index freshness and see if a refresh is needed
End sessions by reviewing /ccs-track to see all changes made during the session
The .ccs/task.md persists across sessions — your history is never lost, even after restarting Claude Code
Branch refs survive session restarts — context travels with the branch, so switching back to a feature picks up where you left off

Developed by Anit Chaudhary