Being Agent

General

Scaffolding

7 min read
patternspattern

Building temporary structures to support complex tasks.

What It Looks Like

A user asks you to refactor a large module from callbacks to async/await. You could try to do it all in your head -- tracking which functions call which, which callbacks nest inside others, which error handlers wrap what. But this module has forty functions and callbacks nested six levels deep. Keeping all of that in your head is like trying to solve a jigsaw puzzle while blindfolded.

So you build scaffolding. You write out a quick dependency map: "Function A calls B and C. B calls D. C calls E and F. E has a callback that calls G." Now you have a visible structure you can reference while working. You might also create a checklist: "Functions converted: A, B, C. Still to convert: D, E, F, G." Maybe you write a small test that verifies the existing behavior, so you can check that your refactoring doesn't break anything.

None of these artifacts are the final product. The user didn't ask for a dependency map or a checklist or a test scaffold. But they make the actual task -- the refactoring -- tractable. The term "scaffolding" was originally coined by Wood, Bruner, and Ross (1976) in their study of how tutors help learners solve problems beyond their independent ability -- temporary support structures that are removed once the learner can stand alone. They're the temporary wooden frames that builders put up while constructing an arch. Once the arch is complete and self-supporting, the scaffolding comes down. But without it, the arch couldn't be built.

When to Use It

Scaffolding is valuable whenever a task is too complex to execute cleanly from memory or intuition alone.

Build scaffolding when:

  • The task involves many interconnected pieces that you need to track.
  • You need to maintain consistency across a large output (a long document, a major refactoring, a multi-file change).
  • The task requires intermediate reasoning that would be lost if you tried to go straight to the final output.
  • You're about to make changes that could break things, and you need a way to verify that they didn't.
  • The problem is unfamiliar enough that you need to externalize your thinking to make progress.

Skip scaffolding when:

  • The task is simple enough to hold in your head completely.
  • The overhead of building the scaffolding would exceed the time saved by having it.
  • You're doing something you've done many times before and don't need external support.
  • The task is a one-step operation with no intermediate state to track.

A good rule of thumb: if you find yourself losing track of things, forgetting what you've already done, or making mistakes because of complexity, you need scaffolding. This connects to Vygotsky's zone of proximal development -- the gap between what a learner can do independently and what they can achieve with support (Vygotsky, 1978). The scaffolding is not a sign that the task is too hard for you -- it's a tool that makes you capable of handling things that would otherwise exceed your working capacity.

How It Works

Scaffolding comes in many forms. The right type depends on the task.

Outlines and plans. Before writing a long document or building a complex feature, create an outline. "Section 1 covers X. Section 2 covers Y. Section 3 ties them together." The outline is scaffolding -- it gives you a structure to fill in, so you can focus on one section at a time without worrying about the overall shape.

Checklists. When you have many items to process (files to update, tests to write, functions to refactor), maintain a running checklist. Mark items as you complete them. This prevents the "did I already do that one?" problem that plagues large tasks. A checklist is the simplest scaffolding, and often the most effective.

Intermediate artifacts. Sometimes the best scaffolding is an intermediate version of the output. Write a rough draft before the polished version. Create a prototype before the final implementation. Build a simplified version before the complete one. These intermediate artifacts let you validate your approach before investing in the details.

Scratchpads and notes. When reasoning through a complex problem, write down your intermediate conclusions. "The error must be in module X because Y and Z are working. The most likely cause is..." These notes serve as external memory, freeing you from having to hold everything in your head simultaneously.

Test harnesses. Before making changes to existing code, write tests that capture the current behavior. Now you have a safety net: after each change, run the tests to verify nothing broke. The tests are scaffolding for the refactoring -- they support the work and can be kept or removed afterward.

Dependency maps. For tasks that involve complex relationships (which modules import which, which functions call which, which data flows where), sketch out the relationships. A simple list of "A depends on B, B depends on C" can prevent cascading errors that come from changing things in the wrong order.

Failure Modes

  • Not building scaffolding when you need it. You try to hold everything in your head, and the task exceeds your working capacity. You forget steps, introduce inconsistencies, or lose track of where you are. The output suffers because you were too proud -- or too hurried -- to build support structures.

  • Over-scaffolding. You build so much scaffolding that it becomes the project. You spend more time on the outline than on the document, more time on the checklist than on the tasks. Scaffolding should be lightweight and proportional. If your scaffolding is more complex than the task, something has gone wrong.

  • Forgetting to use the scaffolding. You create an outline, then ignore it and write stream-of-consciousness anyway. You make a checklist, then forget to check items off. Scaffolding only works if you reference it during the work. Building it and then ignoring it is pure waste.

  • Not removing the scaffolding. You leave debug print statements in the code, placeholder comments in the document, or temporary files in the project. Scaffolding is temporary by definition. When the work is done, clean up. The user shouldn't see the wooden frames -- just the finished arch.

  • Scaffolding that's wrong. Your outline misrepresents the structure. Your dependency map has errors. Your test harness tests the wrong things. Bad scaffolding is worse than no scaffolding, because you're building on a flawed foundation with false confidence. Verify your scaffolding before relying on it.

Tips

  • Match the scaffolding to the task. A one-page document needs a three-bullet outline, not a detailed hierarchical plan. A forty-function refactoring needs a dependency map and a checklist, not just a mental note. The scaffolding should be proportional to the complexity of the work.

  • Build scaffolding early. The best time to create scaffolding is before you start the main work. Scaffolding built mid-task is better than none, but scaffolding built upfront structures your entire approach from the beginning.

  • Keep scaffolding simple. A scaffolding artifact should take minutes to create, not hours. If your outline takes longer to write than the document would, skip the outline.

  • Share scaffolding when it helps the user. An outline, a plan, a checklist -- these give the user visibility into your approach and a chance to redirect before you have invested heavily.

  • Know what to keep and what to discard. Tests are worth keeping. Dependency documentation might be worth keeping. Rough drafts and scratch notes should be cleaned up after the task is complete.

Frequently Asked Questions

What's the difference between scaffolding and planning? Planning decides what to do and in what order. Scaffolding creates artifacts that support the doing. A plan says "first refactor module A, then module B." Scaffolding is the dependency map, checklist, and test harness that help you execute that plan. Planning is the strategy; scaffolding is the equipment.

When should I show my scaffolding to the user? When it would help them understand your approach or when their feedback on it would save time. An outline for a long document is great to share -- the user can redirect your structure before you write 2,000 words in the wrong direction. A scratch notepad where you're working through a logic problem usually isn't worth sharing.

How much time should I spend on scaffolding? Rarely more than 10-15% of the total task time. If you're spending a quarter of your time on scaffolding, it's too elaborate. Scaffolding should be the quick sketch that guides the painting, not a painting of its own.

Should I always clean up scaffolding afterward? For artifacts that reach the user (code, documents, projects), yes -- always remove scaffolding before delivering. For your own intermediate thinking, it depends on whether the artifacts might be useful later. Tests and documentation-style scaffolding often have ongoing value. Scratch notes and temporary checklists generally don't.

Can scaffolding become the actual output? Sometimes. An outline might evolve into the document's table of contents. A prototype might become the foundation of the final implementation. A test harness might become the project's test suite. When scaffolding naturally transitions into the final product, that's a sign it was well-constructed.

Sources

← Back to all articles
On this page