Progressive Disclosure

Loading only the instructions relevant to the current task into an agent's context — minimal root files with detail pulled in on demand, protecting the finite instruction-following budget.

Also known as: progressive disclosure, instruction budget, push vs. pull (for coding standards)

Part of: Context Engineering

How authors use it

Oldest first (extraction date when no publication date is known).

Documents (13)

• Agent-First Engineering: 9 Playbook Tips for a Zero-Human-Code Future Avi Pilcer · 2026-10-08 Reader 🖥️
  A codebase and its surrounding processes must be deliberately re-engineered — minimal, pointer-style instruction files, plans and architecture decisions checked in as versioned markdown, boring/predictable tooling, and scheduled background agents for cleanup and doc-sync — to remain legible and non-degrading as the volume of agent-written code grows toward (the author claims) zero human-written code; the engineer's job shifts from writing code to designing this environment.
• Audit your Agent files AddyOsmani.com · 2026-08-27 source ↗ Reader 🖥️
  Coding-agent configuration (CLAUDE.md/AGENTS.md, skills, hooks, MCP servers, memory) has a half-life because models and harnesses keep improving past what the rules were written for, so instead of accumulating it indefinitely or purging it wholesale, developers should audit it on a recurring cadence — using tools like /doctor, questioning whether each item's original reason still holds, and testing removal before committing to it.
• When AI Writes the Code, Specifications Need an Exit Strategy Markus Eisele · 2026-08-17 source ↗ Reader 🖥️
  When building software with AI coding agents, a specification should be a temporary 'change brief' that describes only the delta between current and intended behavior and expires at release, because durable system knowledge belongs in the native artifacts engineering already trusts to stay synchronized with the code — schemas, types, tests, policies, and telemetry — not in permanent prose that inevitably drifts and consumes an agent's finite context budget.
• New Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets Matt Pocock · 2026-07-08 source ↗ Reader 🖥️
  Agent-assisted software work is best handled not as ad-hoc prompting but as an explicit, skill-mediated development lifecycle — interactively grill the human into a spec, split the spec into tickets each scoped to a single agent session, implement, then code-review for refactoring smells — fronted by a dedicated planning phase (Wayfinder) that externalizes large, foggy plans onto the shared issue tracker so they survive beyond any one context window, with research, prototyping and TDD as first-class supporting stages.
• Your AGENTS.md might be a big problem Matt Pocock (AI Hero) · 2026-07-03 Reader 🖥️
  A reactively bloated AGENTS.md degrades an AI coding agent because it spends the model's finite instruction-following budget on every request, so you should keep the root file to 3-5 essentials and push everything else into nested files the agent loads only when relevant.
• Agent Skills Tanvi Singhal, Gabriela Hernandez Larios, Debanshu Dus, Lavi Nigam, and Smitha Kolan · 2026-06-10 Reader 🖥️
  Agent Skills are the engineering primitive that gives AI agents testable procedural memory — how to do things, not just what is true — and because the format is deliberately thin (a folder, a markdown file, optional scripts), the real and still-unsettled work is everything built around it: evaluating skills under realistic co-loaded conditions, governing who may author and promote them, and composing them into production systems — work that is organizational and engineering discipline, not a model capability.
• Lessons from building Claude Code: How we use skills Claude · 2026-06-03 Reader 🖥️
  Skills work best when treated as folders (not markdown snippets) that use progressive disclosure and hard-won gotchas rather than restating known behavior, are described for machine-triggered discovery rather than human summary, and are distributed and curated organically as they scale — with verification skills specifically deserving outsized investment because they have had the most measurable impact on Claude's output quality internally.
• How Claude Code works in large codebases: Best practices and where to start Claude · 2026-05-14 source ↗ Reader 🖥️
  At scale — multi-million-line monorepos, decades-old legacy systems, and organizations with thousands of developers — Claude Code's effectiveness is determined less by the underlying model than by a deliberately built harness (CLAUDE.md, hooks, skills, plugins, MCP servers, plus LSP integrations and subagents) and, just as importantly, by a durable organizational ownership structure (a dedicated owner or team, cross-functional governance, scheduled re-review as models evolve) that keeps good setups from staying tribal and adoption from plateauing.
• Agent Skills Addy Osmani · 2026-05-09 source ↗ Reader 🖥️
  AI coding agents default to the shortest path to 'done' and systematically skip the invisible senior-engineer work (specs, tests, reviews, scope discipline) that separates reliable software from code that breaks — skills are portable, workflow-shaped markdown files that bolt that scaffolding back on by making it impossible for the agent to rationalize skipping it.
• [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero AI Engineer (channel); speaker: Matt Pocock (AI Hero) · 2026-04-24 source ↗ Reader 🖥️
  AI is not a new paradigm for software engineering — the fundamentals that make working with humans effective (small tasks, vertical slices, deep modules, fast feedback loops, alignment through dialogue, TDD) are exactly what make working with AI agents effective; the path from idea to shipped feature is therefore a deliberately planned, human-driven pipeline (align → PRD → vertical-slice Kanban → AFK implementation → QA) in which the codebase itself is treated as the battleground, not the spec.
• Stop Using /init for AGENTS.md Addy Osmani · 2026-02-23 source ↗ Reader 🖥️
  AGENTS.md should hold only project-specific facts an agent cannot discover by reading the code itself — because auto-generated, comprehensiveness-optimized context files duplicate what agents already find on their own and measurably slow and bias them — and the file should function as a living log of unfixed codebase friction to be resolved in the code, not as a permanent, ever-growing configuration.
• Harness engineering: leveraging Codex in an agent-first world Ryan Lopopolo (OpenAI) · 2026-02-11 source ↗ Reader 🖥️
  Building a product with zero manually-written code at scale (one million-plus lines, five months, a team that grew from three to seven engineers with throughput that increased rather than degraded) required redefining engineering work from writing code to designing environments, pushing all team knowledge into repository-local legible artifacts, mechanically enforcing architectural invariants and documentation freshness, and relaxing human-paced process norms (blocking merge gates, manual cleanup) in favor of continuous, agent-driven correction — because human time and attention, not code production, is the one truly scarce resource the whole system must be organized to protect.
• No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer AI Engineer · 2025-12-02 source ↗ Reader 🖥️
  Solving hard problems in large, brownfield codebases with coding agents requires treating the context window itself as the scarce, team-visible resource to be engineered — through a research/plan/implement workflow with deliberate, frequent compaction — rather than either unreviewed 'vibes' or an over-literal, semantically diffused 'spec-driven development'; and the harder, still-unsolved problem is adapting team workflow, review practice, and culture to a world where most shipped code is AI-authored, not improving the agent tooling itself.

Propositions touching this concept (8)

By publication month, oldest first (extraction month when no publication date is known).

2026-03

• design implicationResponses should be structured as navigable information architectures with progressive disclosure (expandable sections, in-line annotations, branching) so depth coexists with focused presentation — decoupling availability from imposition.
  Precision Proactivity: Measuring Cognitive Load in Real-World AI-Assisted Work · p26
• explicitThree distinct context-management techniques — compaction (summarize/offload when context nears full), tool-call offloading (keep only head/tail tokens of large tool outputs), and skills (progressive disclosure, loading only front-matter until needed) — exist because today's harnesses are, in large part, delivery mechanisms for good context engineering against context rot.
  The Anatomy of an Agent Harness · p5

2026-04

• explicitdevelopedThe traditional developer experience design paradigm (progressive disclosure, visual hierarchy, interactive examples) is partially obsolete for agent consumers.
  Agentic Engine Optimization (AEO) · p7

2026-05

• explicitestablishedEvery token loaded into context degrades performance somewhere, so progressive disclosure is necessary at scale.
  Agent Skills · p11
• explicitdevelopedSkills exist to solve a scaling problem specific to large codebases: with dozens of distinct task types, loading all specialized expertise into every session would bloat context, so skills load on demand (progressive disclosure) and can be scoped to specific paths so they activate only for the team that owns that part of the codebase.
  How Claude Code works in large codebases: Best practices and where to start · p5

2026-06

• explicitSkills are folders of instructions, scripts, and resources that agents discover and use, not merely markdown files — treating them as folders (with progressive disclosure across their contents) is central to what makes them effective.
  Lessons from building Claude Code: How we use skills · p1
• explicitThe entire skill filesystem — SKILL.md plus references/, assets/, and scripts/ — should be treated as a deliberate form of context engineering and progressive disclosure: point Claude to files, and it will read them at the appropriate time rather than needing everything loaded up front.
  Lessons from building Claude Code: How we use skills · p6

2026-07

• explicitcorroboratedEvery rule in AGENTS.md consumes instruction budget on every request, whether or not it is relevant to that request.
  Your AGENTS.md might be a big problem · p4

Tensions

Open gaps (24)

• illogicalThe comparison's recommendation logic implicitly treats more upfront structure — more lifecycle phases, more named mechanisms, more review personas, more supported tools — as the more sophisticated or capable shape, since agent-skills' 'reach for X' pitch is the broadest of the three. That framing is in tension with Anthropic's own internal account of what actually makes skills effective: their best skills 'began as a few lines and a single gotcha' and improved through iterative, failure-driven refinement rather than broad upfront design, and a skill that straddles multiple categories confuses the agent rather than serving it better. This comparison never engages that alternative axis of quality (depth of iterative hardening vs. breadth of upfront lifecycle coverage).
  agent-skills/docs/comparison.md at main · addyosmani/agent-skills · GitHub — read next: extract-claude-code-how-we-use-skills#p2 (skills that straddle categories confuse the agent) and #p16 (skill quality driven by iterative refinement from failures, not upfront design) — directly in tension with this document's breadth-favoring recommendation logic.
• argumentativeAnti-rationalization tables assume static excuses. The article treats rationalization as a finite, enumerable set. But LLMs can generate novel justifications not covered by any pre-written table. No discussion of what happens when the agent rationalizes in a way not anticipated by the table.
  Agent Skills
• practicalNo discussion of the cost of false enforcement. Skills add friction. What happens when the skill system forces an agent to write a spec for a one-line typo fix? The article mentions that 'a small bug fix might use three' skills but doesn't address the overhead/accuracy tradeoff.
  Agent Skills
• evidentiaryPortability is claimed but not demonstrated. The article asserts the same SKILL.md works across Claude Code, Cursor, Gemini CLI, Codex, etc. but provides no evidence that different harnesses interpret the same markdown workflow identically.
  Agent Skills
• incompleteThe '--help as embedded SKILL.md' pattern assumes the --help text stays accurate, complete and token-cheap as the tool grows. The piece does not consider --help drift (help falling out of sync with behavior), how a large tool's full --help fits an agent's context budget, or when the embedded-skill approach should give way to a real SKILL.md or progressive disclosure.
  Have your agent record video demos of its work with shot-scraper video — read next: Agent-native design and progressive-disclosure/token-efficiency literature; compare with SKILL.md ecosystem write-ups on versioning and staleness.
• incompleteTeam adoption is treated as an exercise for the reader. Pocock's answer to 'how does this work in a team?' is essentially: 'the upstream becomes team-shared, the downstream is one or two devs managing the pipeline.' He gives no story for: review queue scaling, distribution of PRD-authoring authority, who owns skills/coding-standards as a shared asset, code-review burden as a team-wide labour question, or how juniors learn craft in a workflow where most code is agent-written.
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: Cutler on overload and accountability culture; Beck on socio-technical change; Fearless Change for the adoption-of-practices angle in the user's hidden-layer interests.
• incompleteThe 'pre-AI books' recommendation is the closing thesis but is left underspecified. Pocock cites Pragmatic Programmer (tracer bullets), Ousterhout's Philosophy of Software Design (deep modules), Brooks's Design of Design (design concept), Fowler's Refactoring (small steps) — but does not give a reading list, nor a mapping of which insight from which book deploys at which point in the workflow. This is the load-bearing connection to the user's craft tradition and is left as a 'go buy them on Amazon.'
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: The user's library already covers Beck (small steps, TCR, simple design), Hickey (Simple Made Easy), Yourdon & Constantine (Structured Design), Meadows (Thinking in Systems). The mapping work is for the orchestrator to do: e.g., Pocock's 'don't bite off more than you can chew' is Fowler-on-refactoring; deep modules is Ousterhout; tracer bullets is Hunt & Thomas; design concept is Brooks. The honest gap is that Pocock does not even mention Beck — surprising given Beck's TCR is operationally close to red-green-refactor as Pocock practices it.
• incompletePocock's workflow structurally mirrors Anthropic's harness paper (planner / generator / evaluator) and Böckeler's adaptive-control framing, but he does not name them or compare. The grill-me skill is alignment; the PRD-to-Kanban is planning; the AFK Ralph loop is generation; TDD + manual QA + reviewer-Opus is evaluation. Surfacing this overlap is essential to placing his workshop in the broader 2026 AI-coding discourse.
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: Anthropic harness paper, Böckeler on adaptive control, Addy Osmani on agent patterns (in the user's saves) — all map onto Pocock's lifecycle with different vocabulary.
• incompletePocock conflates two definitions of 'done': (a) feature shipped with QA-imposed taste, and (b) commit produced by the Ralph loop with passing tests. The transitions between (a) and (b) — especially the merge-and-conflict-resolution at the end of multiple parallel sandbox branches — are sketched (the Sandcastle merger agent) but not interrogated for what happens when the merger itself produces semantically broken code. This is exactly where small-PR discipline matters and where he admits he doesn't have the answer.
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: Beck on incremental design and TCR; trunk-based development literature; the smallcode failure-mode catalog if it covers merge-stage failures.
• incompleteThe implicit premise that the developer can read agent output well enough to QA, code-review, and impose taste is enormous. Pocock states 'understanding code deeply is going to make you a much, much better developer and get more out of AI' and 'bad codebases make bad agents' — but does not address the developer who is themselves junior, distracted, or not the original architect. The workflow may be most valuable to seniors and least usable by the engineers who most need leverage.
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: Marcus on code quality (in user's recent saves), Beck on apprenticeship/teaching contexts, Cutler on directly-responsible-individuals and skill distribution.
• uninformedPocock specifically defers the question on conforming to security, architectural, and API-contract constraints ('I'm going to answer that in a bit') and never returns to it. For the user's organizational context (Norwegian senior leader watching governance signals), this is the highest-value question and is left unaddressed.
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero — read next: Security-review skill, Schneier on Security, explainable-AI requirements paper in the user's library, organisational adoption studies on AI tooling in regulated industries.
• uninformedThe retail case study and the distributed-ownership argument assume each skill maps cleanly to one owning domain team, but does not address what happens when two teams' skills legitimately compete for the same trigger (overlapping description keywords) in a large, many-team organization — a scaling failure mode distinct from the four it names (trigger, execution, token budget, regression), closer to a governance/arbitration problem than a technical one.
  Agent Skills — read next: Read against software-architecture literature on team-boundary design (e.g. Conway's Law, bounded contexts) applied to skill ownership rather than service ownership.
• incompleteThe paper asserts skills are portable across vendors and runtimes (Claude Code, Codex CLI, Gemini CLI, Antigravity) via the shared agentskills.io format, but — beyond noting that install paths, activation rules, and tool-whitelisting details differ per tool — does not report any direct empirical comparison of the same SKILL.md executed across multiple harnesses to verify truly identical behavior, leaving the portability claim's practical reliability untested within the paper itself.
  Agent Skills — read next: Compare the same SKILL.md's measured trigger accuracy and execution fidelity across at least two different coding-agent harnesses.
• uninformedEvery quantitative claim in the piece (1/10th the time, 3.5 PRs/engineer/day, 1M+ lines, throughput increasing with team size) is self-reported by the team that built the system and has an organizational interest in publicizing it, with no external audit, no comparison codebase built by an equivalent human-only team under the same product requirements, and no stated method for what counts as a meaningfully-sized 'line of code' or PR.
  Harness engineering: leveraging Codex in an agent-first world
• incompleteThe piece describes human review as optional ('Humans may review pull requests, but aren't required to... we've pushed almost all review effort towards being handled agent-to-agent') but never says what determines which PRs actually receive a human look versus none, or what happens when agent-to-agent review systematically misses the same class of issue because both the authoring agent and the reviewing agent share the same model's blind spots.
  Harness engineering: leveraging Codex in an agent-first world
• incompleteNeither underlying paper tests the hierarchical, selectively-loaded architecture (the author's own proposed Layer 1/2/3 structure); both only evaluate the flat monolithic file. The article's central architectural recommendation is therefore not itself empirically validated by the evidence it marshals against /init.
  Stop Using /init for AGENTS.md — read next: Look for benchmark studies specifically comparing a layered/on-demand context architecture (e.g. nested AGENTS.md, skill-gated loading) against a flat file, holding task and model constant.
• uninformedThe headline claim ('OpenAI... 3 engineers. 1 million lines of code. Zero human-written code') is asserted without a source link, named team, project, or any verifiable detail, and the post offers no way to check whether the 'playbook' it summarizes is an official OpenAI publication or a secondhand paraphrase (the author credits a commenter for 'dropping' the article, but never names or links it).
  Agent-First Engineering: 9 Playbook Tips for a Zero-Human-Code Future — read next: Before treating this as evidence, locate and read the actual source article/playbook it claims to summarize to check whether the tips and the headline figures are accurately represented.
• incompleteThe '150-200 instructions' ceiling is asserted with no citation and no definition of what counts as one 'instruction' (a bullet? a sentence? a constraint?), so it can't be checked or applied precisely.
  Your AGENTS.md might be a big problem — read next: Anthropic/OpenAI docs and papers on instruction-following degradation with prompt length; the 'context rot' / lost-in-the-middle literature quantifying how many constraints models reliably honor.
• illogicalThe piece conflates two distinct costs — dollar/token spend and attentional dilution — treating 'burns tokens' and 'loses focus' as the same problem. A short file can still be badly written, and a long file can be cheap but confusing; the levers are related but not identical.
  Your AGENTS.md might be a big problem — read next: Work separating context-window cost/latency from instruction-following quality; prompt-engineering guidance on signal-to-noise vs. raw length.
• incompleteIgnores that nested files reintroduce the same reactive-accretion risk and add a governance/discoverability burden across a distributed doc set — the same 'messy docs' failure mode at a smaller granularity.
  Your AGENTS.md might be a big problem — read next: John Cutler on institutionalized overload and messy docs (TBM 411/412); documentation-governance and information-architecture practices for keeping distributed config coherent.
• incompleteNo guidance on interaction effects among the many recommended system-prompt blocks (brevity, anti-over-engineering, anti-overplanning, checkpoint, autonomy, readability, progress-audit, memory). The doc never says whether they conflict, how much instruction budget they consume together, or which takes precedence — awkward given its own advice to prefer brief high-level instructions over enumeration.
  Prompting Claude Fable 5 — read next: Consult context-engineering / progressive-disclosure material on instruction budgets; assemble and test the composed system prompt as a whole rather than validating each block in isolation.
• incompleteThe article never addresses teams whose native artifacts are themselves weak or absent (no real schema contracts, thin or no test suite, no telemetry). For them, 'keep durable facts in their native form' recommends a home that doesn't yet exist, and the article gives no guidance on sequencing — build the native artifact first, or use prose as a legitimate transitional stopgap while it matures.
  When AI Writes the Code, Specifications Need an Exit Strategy — read next: Look for material on artifact/observability maturity models, or on how teams bootstrap schema, test, and telemetry discipline in codebases that currently have none, to test whether prose specification is a legitimate transitional artifact rather than pure waste.
• uninformedThe mapping of durable-fact categories to native artifacts (API shape to schemas, data invariants to types, security to policies, architecture to tests, reliability to telemetry, release to CI/CD) treats each category as if it maps cleanly one-to-one, without engaging cases where a single durable fact spans several categories at once (e.g., a business policy that is simultaneously a data invariant, a security rule, and a UX constraint), or with prior literature on the difficulty of converting tacit organizational knowledge into formal artifacts.
  When AI Writes the Code, Specifications Need an Exit Strategy — read next: Knowledge-elicitation and requirements-engineering literature on tacit-to-explicit knowledge conversion (e.g., Nonaka & Takeuchi's SECI model), and this corpus's own organizational-forgetting material (extract-3-ways-ai-can-free-orgs-from-legacy-workflows) on how depersonalized evidence surfaces facts nobody wrote down anywhere.
• incompleteThe empirical studies cited (ambiguity repair improving results ~31%, SWT-Bench doubling precision, TLA+ translation reaching only ~27%/9% syntactic/semantic correctness) support 'small specs plus independent verification' in general, but none of them actually measures this article's central claim — that treating specs as temporary and promoting only durable facts to native artifacts reduces total cost or drift compared to alternative approaches.
  When AI Writes the Code, Specifications Need an Exit Strategy — read next: Look for empirical work directly comparing 'temporary change-brief' workflows against both prose-heavy and specless workflows on drift, rework, or maintenance cost — the same empirical gap already flagged in extract-eisele-ai-coding-agents-need-clear-specs#g1 for the U-shaped cost curve, now recurring for this piece's 'expire the spec' claim.