Context Curation & Rules Hygiene

1. Concept Overview & Systemic Problem

Developers often treat files like .cursorrules or .clinerules as dumping grounds:

• A bug arises? A rule is added: "Never use library X".
• A week later, another developer adds: "Use library X for quick operations".
• Three months later, the file turns into an unreadable scroll of 80 conflicting directives.
• The model is forced to read this chaos with every request, wasting tokens and losing generation quality.

Context Curation is a discipline of minimalism and architectural cleanliness: system rules must be modular, hierarchical, relevant, and concise.

2. Architectural Taxonomy & Mental Model

┌─────────────────────────────────────────────────────────────┐
│                 MODULAR CONTEXT HIERARCHY                   │
├─────────────────────────────────────────────────────────────┤
│ 1. ROOT RULES (.cursorrules / AGENTS.md) [Max 150 lines]    │
│    • Core stack & strict boundaries (Next.js 15, Drizzle)   │
│    • Ban-list (No any, no ts-ignore, no unverified deps)    │
│    • Verification command: `pnpm check && pnpm test`        │
├─────────────────────────────────────────────────────────────┤
│                          │                                  │
│                          ▼ On-demand dynamic loading        │
├─────────────────────────────────────────────────────────────┤
│ 2. DOMAIN SKILLS & SUBSYSTEM SPECS (.agents/skills/)        │
│    • `skills/better-auth/` ➔ loaded ONLY during auth tasks   │
│    • `skills/seo-audit/`   ➔ loaded ONLY for marketing pages│
│    • `skills/db-migrations/` ➔ loaded ONLY for schema edits │
└─────────────────────────────────────────────────────────────┘

3. Technical Pipeline & Internal Mechanics

01. Negative Constraints

Instead of lengthy descriptions on how to write code, quality rules clearly articulate prohibited actions:

## Strict Invariants
- NEVER run `npm run build` locally during dev; use `tsc --noEmit`.
- NEVER use inline CSS styles; use Tailwind design tokens.
- NEVER invent mock user IDs; query database fixtures.

02. Using Relative References Instead of Code Duplication

Instead of copying the entire types file into .cursorrules, specify references:

Before modifying database entities, read schema definitions in [schema.ts](file:///src/db/schema.ts).

Modern agent environments will autonomously pull the file content as needed.

4. Production Engineering Scenarios

01. Negative Constraints

Implementing strict rules to avoid common pitfalls in coding practices.

02. Modular Skill Loading

Dynamically loading only relevant skills based on the task context to optimize performance.

03. Regular Rule Audits

Conducting monthly audits to ensure rules remain relevant and up-to-date with the project evolution.

5. Pitfalls, Common Mistakes & Security

• Attempting to Teach the Model Language Through Rules: Avoid writing lectures in rules about what asynchronous programming is in JavaScript or how promises work. The model already knows this. Rules should be specific to your repository's context.
• Loss of Relevance: If the project transitions from Tailwind v3 to Tailwind v4, old rules with outdated utilities will cause syntax errors. Conduct monthly rule audits.

6. Strategic Conclusion for the 2026 Engineer

The quality of an agent's performance is directly proportional to the cleanliness of the context you provide. Context curation is the digital equivalent of cleanliness on a surgical table: unnecessary tools are removed, and essential ones are placed in designated spots.