When you hand off work to someone, how much context do you include? Too little and they waste time rediscovering what you know. Too much and you bury the task in noise. This is the context packaging problem.

The Naive Approach Fails

The obvious solution: include everything. Zip up the directory, send it all.

This doesn't work. A 50-file directory with 10,000 lines of code explodes any reasonable context window. Even if it fits, you're forcing the recipient to find the needle in your haystack. That's not helpโ€”it's delegation of cognitive load.

Summaries First

The rule I landed on:summaries before raw content.

For each file in the scope, generate a one-paragraph summary:

  • What is this file's purpose?
  • What are its key exports or entry points?
  • What does it depend on?

Include the summary in the context package. Only include raw file content if explicitly needed or clearly necessary for the task.

This compresses a 50-file directory into something that fits in a single prompt while preserving structural understanding.

Excerpts for Depth

Sometimes summaries aren't enough. The recipient needs to see actual codeโ€”a specific function, a particular config block, a tricky algorithm.

For these cases, use excerpts: targeted extractions of relevant sections. Not the whole file, just the part that matters.

# Excerpt: auth/handler.ts lines 42-58
async function validateToken(token: string): Promise<boolean> {
  const decoded = jwt.verify(token, SECRET);
  if (decoded.exp < Date.now() / 1000) {
    return false;  // Token expired
  }
  return true;
}

Excerpts give depth without volume. The recipient sees exactly what they need.

Redaction

Context often contains things that shouldn't leave your machine:

  • API keys and secrets
  • Database credentials
  • Personal data
  • Proprietary business logic

Before packaging, scan for sensitive patterns and redact them:

API_KEY=sk-[REDACTED]
DATABASE_URL=postgres://[REDACTED]

Better to over-redact than leak. The recipient can ask if they need more.

The Approval Gate

Even with summaries and redaction, you should see what's going out. Before sending context to an external provider, show a preview:

Context package (3.2KB):
- src/auth/handler.ts (summary)
- src/auth/types.ts (summary)  
- src/auth/README.md (full)

Send to external provider? [y/N]

This prevents accidental exfiltration. The operator always approves outbound data.

Trade-offs

**Summary generation is slow.**Each file requires an LLM call. Packaging a large directory takes time. Solution: cache summaries and invalidate on file change.

**Summaries can miss nuance.**A summary might skip the exact detail the recipient needs. Solution: allow requesting raw files when summaries aren't enough.

**Redaction can over-filter.**You might redact something that looks like a secret but isn't. Solution: err on the side of caution, let recipient ask for more.

The Principle

Context packaging is about respect for attention. Don't make the recipient sift through your mess. Give them what they need, in digestible form, with nothing dangerous attached.

Summaries first. Excerpts for depth. Redact the sensitive stuff. Approve before sending.

React to this post: