Compress Context and Layer Instructions

Project-level instruction files are most valuable when they perform four functions at once: knowledge compression, preference storage, capability declaration, and retention of failures and successes. Their purpose is not to contain every detail. Their purpose is to place the highest-value information in front of the agent before it begins searching or acting.

A useful instruction architecture also separates global information from local information. Global instructions apply across workspaces. Local instructions describe one project, one client, one domain, or one repository. Mixing the two creates unnecessary context and makes rules harder to maintain.

Knowledge compression replaces repeated workspace scans with a high-information-density project map. Instead of reopening every file to understand a codebase or operating folder, the agent receives a concise description of what the project does, where important artifacts live, which commands are used, which dependencies matter, and how the main components relate.

Compression deliberately sacrifices total comprehensiveness. The goal is a bird's-eye view that lets the agent decide where to look next. A short statement such as "the application is implemented in one main component containing navigation, content sections, and footer logic" can eliminate the need to read a much larger file merely to discover the same structural fact.

Preference storage captures conventions that are not reliably built into the harness. Examples include how to return file paths, how much explanation to provide, whether to open an application after starting it, which programming style to favor, or whether to read platform documentation before attempting a non-trivial integration.

Capability declarations tell the agent what it can already do in the current environment. Without these declarations, an agent may behave as though a tool, workflow, database, browser, or autonomous execution path does not exist. A short capability inventory prevents unnecessary clarification loops and reduces the tendency to hand work back to the user.

Failure and success records preserve hard-won operational knowledge. Every failed attempt eliminates part of the solution space. Every successful shortcut identifies a more efficient path. Recording both lets future runs avoid repeating the same search.

The global and local layers should contain different material:

• Stable information about the user, goals, decision priorities, and communication preferences.
• General reasoning rules and recurring workflow conventions.
• Cross-project capability reminders.
• Broad token- and time-conservation rules.
• Repeated failure patterns that appear across several projects.

• Project purpose and architecture.
• File and folder map.
• Build, test, lint, run, and deployment commands that actually apply.
• Project-specific tools, APIs, data sources, and constraints.
• Local preferences and output locations.
• Project-specific failures, successful approaches, and current limitations.

Unmanaged context creates three costs. First, the agent spends time and tokens rediscovering facts that were already known. Second, long contexts can reduce output quality. Third, repeated file searches and tool calls increase the chance of distraction or failure.

A compressed project map reduces these costs while preserving flexibility. The agent can reason at a high level first, then inspect only the files needed for the current decision. Layered instructions also prevent global preferences from being buried under low-level project details and prevent project-specific conventions from contaminating unrelated work.

Build the local instruction layer after the agent has done enough real work to reveal the project's structure and actual failure modes. Do not begin by filling it with speculative rules. A capable agent often performs well without heavy customization, and premature rules can encode assumptions that have not been tested.

A practical local structure is:

A short explanation of what the workspace is for and what outcomes it produces.

The important directories, files, components, and their relationships.

The actual commands used to run, build, test, preview, deploy, or operate the project.

Project-specific output formats, naming rules, implementation preferences, and expected automatic actions.

Tools, services, data sources, scripts, browsers, databases, and reusable workflows the agent may call.

High-density records of approaches that worked, approaches that failed, and what should not be repeated.

The global layer can use a similar structure but should remain shorter and more stable. It should describe the user's enduring priorities and the recurring behaviors that improve work across many projects.

Compression can omit details that later matter. The summary should therefore point to authoritative files rather than pretend to replace them. Instructions also become stale. Commands change, directories move, tools are replaced, and preferences evolve.

Long instruction files create their own context burden. Contradictory rules can be worse than missing rules because the agent must guess which one has priority. Periodic review should remove duplicates, obsolete facts, and conflicts.

A project summary is not a substitute for observation. It is a routing layer that tells the agent what the project contains and where to inspect when a task requires exact information.

Use instructions as compressed operational memory. Separate stable global rules from local project knowledge, declare available capabilities, and keep the result concise enough to guide action without becoming another source of noise.