Prompt length is not design clarity.
Michael Lynch’s design-document guide argues that the useful document articulates the hard problems, coordinates decisions, and scales its investment with complexity and risk. Its suggested anatomy includes goals, non-goals, scenarios, constraints, interfaces, dependencies, security, monitoring, alternatives, and cross-cutting concerns.[1]
That list is not paperwork cosplay. It is a set of handles a reviewer can grab. “Build settings sync” is a wish. “Sync these fields, never upload secrets, tolerate offline edits, resolve these conflicts, emit these metrics, and preserve this rollback” is a design surface.
The agent cannot honor a boundary that exists only as a vibe.
Specs are moving closer to the execution loop.
GitHub’s Spec Kit describes a staged flow—establish principles, specify, plan, decompose tasks, implement, then converge against the earlier artifacts. Its bug extension similarly separates assessment, fix, and test rather than jumping from report to patch.[2]
The interesting move is not that prose magically became executable. It is that the implementation has something durable to disagree with. A diff can now violate a named non-goal, skip an interface, or fail a proof gate. That is much better than asking whether the output “looks right.”
Scheduled agents make weak intent recur.
VS Code 1.137 introduces preview automations that can run agent prompts on demand or on hourly, daily, and weekly schedules. The release notes suggest recurring jobs such as catching up on changes, triaging issues, and finding bugs.[3] Repetition raises the price of fuzzy instructions: one vague run is annoying; a vague run every hour is policy.
A scheduled instruction therefore needs more than a task sentence. It needs scope, stop conditions, allowed side effects, evidence requirements, escalation rules, and an owner for the result. Frequency is an amplifier, not a substitute for supervision.
Write for disagreement, not obedience.
The best design doc creates productive friction. It names rejected alternatives and explains why. It declares what is deliberately out of scope. It gives reviewers concrete failure scenarios. It says which evidence would change the plan.
For agent work, add one more section: convergence evidence. List the commands, fixtures, accessibility states, performance budgets, screenshots, rollback drills, and human decisions that can close the job. “Tests pass” is too blurry when nobody named which behavior deserved a test.
A garage-grade contract.
- Objective: one observable user or system outcome, plus the metric that says it improved.
- Boundaries: non-goals, forbidden side effects, trust zones, cost and time ceilings.
- Interfaces: inputs, outputs, errors, compatibility, ownership, migration and rollback.
- Proof: named scenarios, commands, fixtures, telemetry, review gates, and unresolved evidence.
Keep the doc proportional. A risky migration may deserve twenty pages; a small UI fix may need one crisp screen. The point is not bulk. The point is to make consequential assumptions visible before implementation hardens them.