When I asked Antigravity to refactor my wallpaper app, the agent wrote flawless code. The TypeScript types were clean, the tests passed, and the performance metrics improved. But something was wrong.
This particular app has been downloaded every day since 2014—more than 50 million times in total. The vast majority of those users aren't there for features. They come for stillness. The agent's code was technically correct, but it had quietly removed the breathing room that made the app feel like itself for twelve years.
My instructions said "refactor." I told the agent What. I never told it Why.
When Correct Code Does the Wrong Job
Antigravity agents follow instructions faithfully. Say "refactor," and they'll reorganize the code according to modern best practices. That's technically correct. But without the context of why this refactor matters now or what this codebase is designed to protect, the agent defaults to a rational, generic solution.
Most AI agent misjudgments don't come from faulty instructions. They come from missing intent.
This is a distinctly indie developer problem. In enterprise settings, requirements docs, design specs, and code review conventions silently fill in the why. But when you're building solo, the context that explains why a piece of code was written the way it was lives only in your head. The agent has no access to it.
After more than a decade of solo development, I kept running into this problem. The answer I eventually found is what I now call Why-context design.
The Quiet Chaos of What-Only Context
Let's start with a typical failure pattern.
Before (What-only context):
# AGENTS.md
## Project Overview
Wallpaper app for iOS. Built with Swift + SwiftUI.
## Tech Stack
- Swift 6
- SwiftUI
- PhotosUI framework
- Cloudflare R2 (image storage)
## Rules
- Use Swift Concurrency
- Handle errors carefully
- Write testsIf you ask an agent with this AGENTS.md to "improve performance," what does it consider? Image preloading, cache optimization, parallel fetching, UI restructuring. All of these are valid "performance improvements."
But maybe what users of this app actually need isn't faster image transitions—it's the quiet feeling of opening the app and seeing something beautiful without any effort. That's not in the AGENTS.md.
After (Context that includes Why):
# AGENTS.md
## Project Overview
Wallpaper app for iOS. Running since 2014, over 50 million downloads.
## What This App Protects (Why)
This app's users aren't looking for features. They want a quiet, frictionless experience.
Twelve years of reviews consistently point to "simplicity" as the reason people keep coming back.
Not adding is more important than adding. New features risk disrupting long-time users.
Unless explicitly instructed otherwise, all changes should preserve existing behavior conservatively.
## Tech Stack
- Swift 6
- SwiftUI
- PhotosUI framework
- Cloudflare R2 (image storage)
## Decision Criteria for Changes (Why)
Always ask: "Would this change confuse someone who has used this app for five years?"
Performance improvements should stay within UX boundaries—don't change how things feel.
Settings screen structure should not change (users have muscle memory for where things are).
## Rules
- Use Swift Concurrency
- Handle errors carefully
- Write testsThe difference is significant. With "protect stillness" and "don't confuse long-time users" written into the context, the agent's decision space narrows before it even starts working.
5 Principles of Why-Context Design
These principles emerged from ten years of solo development and prior experience in systems design at NTT DATA. They aren't theoretical—they came from specific failures and the patterns I discovered while fixing them.
Principle 1: Write the Purpose in One Sentence (Clarify "For whom")
If you can't answer "what is this code for, and for whom?" in a single sentence, the agent can't either.
## Who This Code Serves (Principle 1: Purpose)
This API exists for busy professionals who pull out their phone to find a wallpaper during a brief break.
Response under 1 second, one tap to set, nothing else needed.Principle 2: Explain Why Constraints Exist ("Why not")
Writing constraints without reasons leaves the agent guessing at edge cases. Explaining the backstory dramatically improves judgment accuracy.
## What We Don't Do (Principle 2: Why Constraints Exist)
- No social sharing feature
Reason: We implemented this once. After sharing, users didn't return to the app—session time dropped.
- No login required
Reason: This user base values anonymity. Account walls have historically caused uninstalls.Principle 3: Indicate Where the Code Is Heading ("Direction")
Writing where the codebase is going prompts the agent to design for future extensibility. Conversely, writing "this is enough for now" prevents unnecessary abstraction.
## Where This Code Is Going (Principle 3: Direction)
This module will be ported to Android within 6 months.
For now, prioritize speed over elegance. Skip complex abstractions—get it working first.Principle 4: Define "Done" ("Done" criteria)
When agents don't know when to stop, they either over-engineer or under-deliver.
## When This Task Is Complete (Principle 4: Done)
- All existing unit tests pass
- Memory usage confirmed under 50MB in Xcode Instruments
- UIKit and SwiftUI boundaries are clearly separated
All three criteria met = done. Anything else that "could be improved" gets filed as a separate task.Principle 5: Provide Timing Context ("Now")
When you're working on something affects priority. "Before WWDC" or "App Store review coming up" or "user complaints spiking this week" shifts how an agent weighs urgency.
## Why Now (Principle 5: Timing)
Responding to iOS 26 Beta 3 behavior changes. Users have started reporting issues since WWDC.
App Store submission in two weeks. Feature freeze in effect—bug fixes and deprecation replacements only.Implementation Example 1: Integrated AGENTS.md
Here's a complete AGENTS.md incorporating all five principles. This is adapted from the template I actually use in production.
# AGENTS.md (Why-Context Integrated)
## Purpose (Principle 1: For whom)
This app serves users who want their morning phone unlock to feel slightly better.
Emotional ease beats technical sophistication. Ship feeling, not features.
## Architecture Constraints and Reasons (Principle 2: Why not)
- No Redux/TCA
Reason: Solo maintenance is the assumption. Complex frameworks become expensive during framework updates.
- No Firebase (replaced with Cloudflare Workers + R2)
Reason: Reducing Firebase dependency improved App Store approval rates based on direct experience.
- Image compression lives on the server (Cloudflare Worker only)
Reason: Client-side compression generated battery drain complaints in 2022. Lesson learned the hard way.
## Where This Code Is Going (Principle 3: Direction)
Short-term (3 months): Stable iOS operation
Mid-term (6 months): Android port via Kotlin Multiplatform
Long-term: Widget support (WidgetKit + Live Activities)
Architecture decisions should account for the mid-term KMP plan.
Business logic must be fully decoupled from UI layers now to enable future sharing.
## Completion Criteria (Principle 4: Done)
No PR is complete until:
1. `xcodebuild test` passes entirely
2. Xcode Memory Graph confirms no retain cycles
3. Swift Concurrency shows no misuse of `Task.init { @MainActor ... }`
If "possible improvements" exist outside these criteria, file them as separate issues.
## Current Task Context (Principle 5: Now)
iOS 26 Beta 3 compatibility is urgent. User reports have increased post-WWDC.
App Store submission: 2 weeks out. Feature changes frozen. Bug fixes and deprecated API replacements only.With this AGENTS.md, an agent won't decide to "also refactor some things for performance while fixing a retain cycle." The "Now" context makes "only fix what's broken" explicit.
Implementation Example 2: Task-Level Intent Context
AGENTS.md covers the whole project. Individual tasks also benefit from embedded Why.
Before (What only):
Update the favorites list stored in SwiftData `@Model` classes
to support pagination.
After (With Why):
## Task: Favorites List Pagination
### What
Update the favorites list stored in SwiftData `@Model` classes to support pagination.
### Why
Three users with 5,000+ saved wallpapers have reported the app freezing on launch.
Two App Store reviews this week used the word "slow."
### Constraints (Why not)
Don't change the visual UI. Use automatic scroll-based loading, not a "Load More" button.
Reason: existing users have muscle memory for the current scroll behavior.
### Done Criteria
App launches in under 3 seconds with 5,000 mock items.
Existing add/remove favorites operations are unaffected.
The same task, but with Why, the agent's choices narrow. Pagination approach, UI impact scope, and performance targets all become clearer.
Implementation Example 3: Self-Diagnostic Error Protocol
When agents get stuck, this prompt pattern uses intent context to guide self-diagnosis.
# Error Diagnostic Protocol (for AGENTS.md)
When you encounter an error you can't resolve, or a judgment call you're uncertain about, work through this sequence:
1. Re-read "Architecture Constraints and Reasons" in AGENTS.md
→ Does this constraint relate to the current problem?
2. Cross-reference "Where This Code Is Going (Direction)"
→ Is the solution you're considering consistent with the mid-term plan?
3. Check "Completion Criteria (Done)"
→ Is this problem within the current task's scope? If not, create a separate issue.
4. If you still can't decide after all three steps:
Report: "This decision falls outside AGENTS.md scope. Proposing options: [A] [B]"
and wait for human input before proceeding.The most important step is number 4. It designs the agent to report rather than silently proceed when facing uncertainty. This single pattern has prevented more production surprises than any other practice I've adopted.
On the Deeper Nature of Passing Context
My paternal grandfather was a Miyajidariku—a traditional Japanese shrine carpenter. Everything he built had reasons: why this wood grain faces this direction, why this joint uses this angle, why this beam is thicker than the adjacent one. None of it appeared in drawings. It was passed through conversation, through watching, through hands that moved with purpose.
Working with AI agents sometimes feels like trying to articulate that unspoken knowledge.
When I first started using Antigravity in earnest, I focused on getting code out of it. Gradually, I realized what separated good results from poor ones wasn't the agent's capability—it was the quality of context I gave it.
There's a practical upside to this: the cost of writing Why-context is front-loaded. Once written, every subsequent task inherits that context automatically. Over time, the cost is far lower than repeatedly correcting an agent that didn't know what you were really after.
But I'll admit there's something more to it than efficiency. When I write out why I built something a certain way, I sometimes discover I don't have a clear answer. That moment—when you can't explain the Why—is useful information. It often means the design needs revisiting, not just the agent instructions.
The Judgment Hierarchy: Stopping Agents from Overthinking
One practical outcome of Why-context is preventing agents from over-deliberating. With sparse context, agents consider more options to compensate. In solo development, that consideration time is your time.
The pattern that's helped most is a three-tier judgment hierarchy in AGENTS.md:
## Judgment Delegation Tiers
### Decide Independently
- Code formatting and naming
- Adding unit tests
- Improving comments
- Type error fixes (without changing logic)
### Report Before Changing (leave a comment first)
- Existing API signature changes
- Adding or removing external dependencies
- Data structure changes that require migration
### Never Do
- App Store Connect configuration
- Changes to billing flows (including Stripe)
- Any modification to privacy-related data handlingWith this hierarchy, agents know what decisions are theirs to make. Fewer questions, fewer surprises, more reliable output.
For more on multi-agent context design, the article on AGENTS.md architecture for multi-agent systems covers complementary territory. And for designing recovery behavior when agents hit errors, Resilient AI Agent Error Recovery Patterns is worth reading alongside this one.
One Step to Take Today
Open the AGENTS.md for a project you're actively working on.
Pick just one of the five principles—whichever feels most missing—and add three to five lines explaining it. Not the rule itself. The reason behind it.
You'll likely find the writing clarifying in its own right. When you struggle to articulate why a constraint exists, that's the agent's problem too. Getting the Why onto the page is as much about building shared understanding as it is about improving output quality.
I'm still working through this myself. But the gap between "agent that writes correct code" and "agent that does the right work" has gotten measurably smaller since I started writing Why into everything.