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:

Always loaded vs conditionally loaded context files
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 /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 /analyze:

Before /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 /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 /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.

Project Structure

MD-First Development

Was this helpful?

Help us improve the documentation by sharing your feedback.