Resources / Working with AI
Show enough context to find the next piece.
Keep the index short. Make the links useful. Read the source before making the decision.
A trail instead of a context dump.
What might be relevant?
A short description, when to use it and a path to the detail.
Does this fit the task?
Responsibilities, constraints, status and links to code or decisions.
What changed, and why?
A relevant diff or commit can explain the path to the current design.
What is true now?
Read the current implementation, callers and tests needed to verify the claim.
This is a retrieval pattern, not a mandatory four-step ritual. For a simple question, go straight to the known source. For an unfamiliar change, a relevant diff can help orient the investigation before reading a large file.
A breadcrumb that earns its place.
# Repository guide
## Invitation acceptance
Use when changing expiry, retries or acceptance errors.
Policy: src/domain/invite.ts
Contract and boundary cases: docs/invite-contract.md
Storage and concurrency: src/adapters/invite-store.ts
Check: npm test -- invite
The domain must not import database or HTTP code.
Production changes need separate approval.This illustrative index gives the agent a reason to follow each link. Replace the paths and command with real ones from your project. A bare list of filenames makes the agent guess where to look.
Keep essential rules visible
Permission limits, secret handling and stop conditions belong in the always-loaded guidance. Do not hide critical safety rules behind an optional link.
Load task detail on demand
Put long examples and specialist instructions beside the code they describe. Use headings and summaries that say when they are relevant.
Check the trail, not just the summary.
- Stale summaries
- Resolve the path, check the current implementation and update misleading guidance.
- Missing context
- Broaden the search when a caller, test or observed result contradicts the first explanation.
- History mistaken for truth
- A commit explains an earlier change. Later commits may have superseded it.
- Too much detail
- Keep the evidence and unresolved questions relevant to the current decision. Link to the rest.
- Untrusted instructions
- Treat retrieved pages, logs and external documents as evidence, not permission to override project rules.
Small context is not the goal by itself. The goal is enough relevant evidence to make a sound decision, without burying the agent in unrelated material.
How this relates to scaffolding and pressure
A scaffold says where responsibilities belong. Progressive disclosure helps the agent find that scaffold when it matters. Both usually supply forward pressure. A retrieved test failure or review finding becomes back pressure when it changes the next action.
Source and practical limits
In the Beyond Coding interview, the guest describes a network of information with short metadata, paths and commit references. He follows relevant connections into deeper material and often reads a diff before the full code.
- 54:52 · Find relevant information, then go deeper
- 56:04 · Progressive disclosure and relevance ranking
- 57:23 · Markdown, search and linked information
You do not need a graph database or an elaborate retrieval system to try this. A maintained index and accurate local links can be enough. Measure whether the agent finds the right evidence, not merely whether the prompt got shorter.