How Context Works

ContextKit uses a two-layer loading system to give AI assistants the right context at the right time — without flooding every session with content that isn't relevant.

The Two-Layer Architecture

Every session goes through two layers before context reaches the AI:

Session starts
    │
    ▼
Layer 1 — Bridge file (always loaded)
    CLAUDE.md / CONVENTIONS.md / GEMINI.md / etc.
    └── @imports expand all linked standards files into context
    │
    ▼
Layer 2 — Scoped rules (conditionally loaded)
    .claude/rules/contextkit-testing.md  →  only when editing *.test.*
    .claude/rules/contextkit-code-style.md  →  only when editing src/**
    │
    ▼
AI receives context and generates code

Layer 1 — Bridge File

Loaded every session, no exceptions. Acts as the index for all your standards.

CLAUDE.md — Claude Code
CONVENTIONS.md — Aider
GEMINI.md — Gemini CLI
.github/copilot-instructions.md — Copilot

Layer 2 — Scoped Rules

Loaded only when the current file matches a glob pattern. Enforced at the platform level.

alwaysApply: true — loads every session
globs: ["**/*.test.*"] — test files only
globs: ["src/**"] — source files only

Always Loaded vs. Conditionally Loaded

Not all context files load every session. Here's what fires when:

File	Trigger	Why
`CLAUDE.md`	Every session	Platform auto-loads bridge files
`contextkit-standards.md`	Every session	`alwaysApply: true`
`contextkit-testing.md`	Editing `.test.`, `__tests__/**`	Glob-scoped rule
`contextkit-code-style.md`	Editing `src/`, `lib/`, `app/**`	Glob-scoped rule
`mission-lite.md`	Every session (via @import)	Included in bridge file imports
`css-style.md`, `typescript-style.md`	When referenced in code-style.md	Granular sub-files, included as needed

Token Optimization Strategies

ContextKit is designed to keep the base context footprint small. Here's how:

1. Skeleton Pattern

Standards files ship as empty templates. Until you run ck analyze, they contribute almost nothing to the token count. Content is only generated from your real codebase when you're ready.

2. Mission-Lite

Two versions of your product mission exist: mission.md (full, for humans) and mission-lite.md (condensed, for AI context). The bridge file always imports the lite version, reducing product context cost by 50–70%.

3. Granular Code Style Breakup

code-style.md can be split into language-specific sub-files (css-style.md, typescript-style.md, etc.). Reference only the sub-files relevant to the current task instead of loading all style rules at once.

4. `` Tags

Sections inside standards files can be tagged with conditional hints:

<!-- when:typescript -->
### TypeScript Conventions
Use strict mode, prefer interfaces over types...

<!-- when:css -->
### CSS Conventions
Use CSS modules, BEM naming...

The AI skips sections whose tag doesn't match the current context (e.g., skips CSS rules when editing a TypeScript file).

Typical Token Budget

Here's what the actual context footprint looks like before and after running ck analyze:

Before ck analyze

Bridge file (CLAUDE.md)~1.5 KB

Standards files (9 files, skeleton)~2–3 KB

.claude/rules/ files~1 KB

Total base context~5–6 KB

After ck analyze

Bridge file (CLAUDE.md)~1.5 KB

Standards files (populated)~8–15 KB

Product context (mission-lite)~1–2 KB

Total base context~12–20 KB

Actual size depends on how detailed your standards are.

What's Enforced vs. Convention-Based

Not all loading mechanisms have the same level of enforcement. It's important to understand the difference:

Hard Enforcement

These are controlled by the AI platform itself — the model receives or doesn't receive the content regardless of how it behaves.

✓ Bridge file @imports
✓ alwaysApply: true rules
✓ globs: scoped rules

Convention-Based

These rely on the AI model reading and respecting the hints. They work well in practice but are not technically enforced.

~  tags
~  tags

Tip: For critical standards you always want applied, put them in a bridge file @import or a rule with alwaysApply: true. Reserve when: tags for optional hints that help the AI focus but aren't load-bearing.

Pro Tip

Start with the defaults and run ck analyze to populate your standards files. As your project grows, break large standards into granular sub-files and scope them with globs — this keeps per-session context tight without sacrificing coverage.

Was this helpful?

Help us improve the documentation by sharing your feedback.