How Context Works

ContextKit keeps a small amount of context loaded every session — one canonical AGENTS.md and a short index — and loads topic standards only when the AI touches files they apply to.

How Context Loads

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

Session starts
    │
    ▼
Layer 1 — Always loaded
    AGENTS.md  (canonical; CLAUDE.md imports it, GEMINI.md imports it,
                Copilot / Windsurf / Aider get the same body)
    .contextkit/standards/index.md  (≤50 lines: rules, commands, pointers)
    │
    ▼
Layer 2 — Path-scoped rules (when matching files are touched)
    .claude/rules/contextkit-testing.md     →  **/*.test.*, **/__tests__/**
    .claude/rules/contextkit-code-style.md  →  src/**, lib/**, app/**, packages/**
    │
    ▼
Layer 3 — Read when relevant (the model follows AGENTS.md's table)
    architecture.md, ai-guidelines.md, workflows.md, glossary.md,
    product/decisions.md, product/roadmap.md, active goal file
    │
    ▼
AI receives context and generates code

Layer 1 — AGENTS.md + index.md

Loaded every session. Kept short on purpose: what to read first, when to read the rest, and the skills.

AGENTS.md — canonical (Codex, OpenCode, Cursor read it directly)
CLAUDE.md — @AGENTS.md + @.contextkit/standards/index.md
GEMINI.md — pointer + @AGENTS.md
.contextkit/standards/index.md — written by /ck setup

Layer 2 — Path-Scoped Rules

Loaded only when the AI touches a matching file. Enforced by the tool itself.

Driven by context_rules in .contextkit/config.yml
Claude Code: paths: frontmatter
Cursor: globs: · Copilot: applyTo:

Why CLAUDE.md imports AGENTS.md

Claude Code reads AGENTS.md on its own only when there is no CLAUDE.md. ContextKit writes a CLAUDE.md that imports it, so there is one source of truth and Claude still gets its Claude-only line (skills, AskUserQuestion for decisions).

Always Loaded vs. Conditionally Loaded

Not all context files load every session. Here's what fires when (Claude Code shown):

Always loaded vs conditionally loaded context files
File	Trigger	Why
`AGENTS.md` / `CLAUDE.md`	Every session	Tool auto-loads its context file
`standards/index.md`	Every session	Imported by CLAUDE.md; AGENTS.md says read it first
`contextkit-testing.md`	Touching `.test.`, `.spec.`, `__tests__/**`	Path-scoped rule
`contextkit-code-style.md`	Touching `src/`, `lib/`, `app/`, `packages/`	Path-scoped rule
`architecture.md`, `glossary.md`, …	When the task calls for it	AGENTS.md "Read When Relevant" table
`goals/<slug>.md`	When a goal has `status: active`	AGENTS.md "Always" section
`.claude/skills/*`	When a skill runs	Only the skill description is loaded up front

Per-Tool Rendering

You describe path scoping once, in .contextkit/config.yml:

context_rules:
  - file: standards/testing.md
    paths: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"]
  - file: standards/code-style.md
    paths: ["src/**", "lib/**", "app/**", "packages/**"]

ck install renders it in each tool's own format. After editing the list, re-render with ck update --force or ck <platform> (e.g. ck claude):

Tool	Rule file	Scope key
Claude Code	`.claude/rules/contextkit-<name>.md`	`paths:`
Cursor	`.cursor/rules/contextkit-<name>.mdc`	`globs:`
GitHub Copilot	`.github/instructions/contextkit-<name>.instructions.md`	`applyTo:`

Other tools (Codex, Gemini, Windsurf, Aider) rely on the "Read When Relevant" table in AGENTS.md. Stale contextkit-* rule files are removed; your own rule files are left alone.

Fixed in 2.0: pre-2.0 Claude rule files used globs:, which Claude Code ignores, so they loaded in every session. They now use paths:. Run ck update to rewrite them.

Keeping Context Small

Always-loaded context competes with your actual task for the model's attention. ContextKit keeps it lean:

1. A Short Index

.contextkit/standards/index.md holds only what the AI needs every session — what the project is, must / must-not rules, exact commands, and a "When you touch X → read Y" table. 50 lines or fewer.

2. Skeleton Standards

Standards files ship as empty templates. /ck setup analyzes your codebase and writes only rules the AI couldn't infer from the code itself, plus the index and context_rules.

3. /ck tidy

Shrinks always-loaded context: prunes generic or linter-enforced rules, wires orphan guides into context_rules, and promotes repeated corrections into standards.

4. Granular Code Style

code-style.md can be split into language-specific sub-files (css-style.md, typescript-style.md). Add each one to context_rules with the paths it applies to.

5. `` 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.

Context Budget Check

ck check includes a stale-context check. It flags instructions that point at missing files or removed skills, and always-loaded context (AGENTS.md, CLAUDE.md, index.md, unscoped rules) over context_budget_lines lines.

ck check --context # only the stale-context checkck check --context --strict # treat warnings as errors

# .contextkit/config.yml
context_budget_lines: 400   # default

The pre-push hook runs the same check as a non-blocking warning when ck is on your PATH.

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.

✓ @AGENTS.md / @index.md imports
✓ The AGENTS.md mirror files (Copilot, Windsurf, Aider)
✓ Path-scoped rules (paths:, globs:, applyTo:)

Convention-Based

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

~ The "Read When Relevant" table in AGENTS.md
~  tags
~  tags

Tip: For critical standards you always want applied, put them in index.md (always loaded) or a path-scoped rule. 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 setup to populate your standards, index, and context rules. As your project grows, split large standards into granular files and scope them in context_rules — then run /ck tidy now and then to keep always-loaded context tight.

Upgrading to 2.0

MD-First Development

Was this helpful?

Help us improve the documentation by sharing your feedback.