Writing Great Feature Descriptions

The single biggest factor in agent output quality is your feature description. A good description is the difference between "the agent built exactly what I wanted" and "the agent went in a completely wrong direction."

Why descriptions matter

An AI agent has no context about your intent beyond what you write. It doesn't know:

• Which existing patterns to follow
• Which files are relevant
• Which approaches you prefer
• What "done" looks like

Your description fills that gap. The more specific you are, the less the agent has to guess.

The anatomy of a good description

Every good feature description covers five areas:

Area	What it defines	Example
What	What you want built	"A search bar that filters products by name and category"
Where	Which files/components to modify	"Add to Products page at /products, edit src/pages/Products.tsx"
How	Approach hints	"Use existing Button component, debounce input by 300ms"
Constraints	Limits and boundaries	"Must work on both desktop and mobile. No new dependencies."
Done	What "done" looks like	"Products page has a search bar. Typing filters products in real-time. Works on mobile."

Bad → Better → Best examples

Example 1: Adding search

❌ Bad (too vague):

"Add search to products page"

The agent: Adds search, but uses a modal, installs a new library, and modifies every file on the page.

✅ Better (covers what and where):

"Add a search bar to the Products page at /products. Filter products by name and category as the user types. Display results below the search bar in a dropdown."

The agent: Adds the right component in the right place. Might over-engineer the dropdown.

⭐ Best (covers all 5 areas):

"Add a search bar to the Products page at /products. Filter products by name and category. Use debounced input (300ms delay). Display results as a dropdown below the search bar using the existing Dropdown component from src/components/. The search bar should be responsive — full width on mobile, 300px max on desktop. Acceptance: typing 'shirt' shows products with 'shirt' in name or category. Empty state: 'No products found.' No new dependencies."

The agent: Exactly what you wanted, no guesswork.

Example 2: Fixing a bug

❌ Bad (too vague):

"Fix the login bug"

The agent: Fixes the wrong bug, or fixes it the wrong way.

✅ Better (covers what and where):

"Fix the login redirect bug: after successful login at /api/auth/login, users are sent to / instead of /dashboard. The redirect URL is set in auth.ts line 42. Change it to redirect to /dashboard."

The agent: Nails the fix on the first try.

Example 3: A multi-file feature

⭐ Best (covers all 5 areas for a complex feature):

"Add a dark mode toggle to the Settings page at /settings.

Where: Edit src/pages/Settings.tsx to add a toggle. Create src/components/DarkModeToggle.tsx for the component. Update src/styles/theme.css with dark mode CSS variables.

How: Use the existing Toggle component from src/components/. Store preference in localStorage. Use CSS custom properties for theming (see existing :root variables in theme.css).

Constraints: Must work on both desktop and mobile. Must not break existing light mode. Follow the existing Settings page layout pattern. No new npm packages.

Acceptance:

• Toggle appears on Settings page below "Notifications" section
• Toggling on applies dark theme immediately
• Preference persists after page refresh
• Toggle is keyboard-accessible
• Edge cases: JavaScript disabled (graceful fallback), localStorage unavailable (graceful degradation)"

Common mistakes

Mistake	Why it hurts	Fix
Too vague	Agent makes incorrect assumptions	Be specific about what, where, and how
Too long / novel-like	Agent misses key instructions	Keep it structured, not narrative
Contradictory instructions	Agent can't satisfy conflicting requirements	Review for internal consistency
Missing context references	Agent doesn't know existing patterns	Mention file paths and component names
No "done" criteria	Agent doesn't know when to stop	Always include acceptance criteria
Over-constraining	Agent follows instructions literally even when wrong	Leave room for the agent to suggest improvements

Before you write

Take 2 minutes to gather context:

1. Open the relevant files in your editor — note the patterns and conventions
2. Check if there's existing CDR knowledge for the area — inject it for better results
3. Check runtime-context.md for architecture decisions that might affect the feature
4. Think about edge cases — loading, empty, error, and success states

Team tips

• Establish a template: Create a team template for feature descriptions (e.g., What / Where / How / Constraints / Acceptance). Consistency helps both agents and reviewers.
• Review descriptions before creating: A 2-minute description review saves 20 minutes of agent rework.
• Learn from rejections: If you keep rejecting the agent's output on the same type of issue, add it to your description template.
• Update descriptions mid-feature: If you add scope mid-way, update the feature description so the agent has the latest context.

Next steps

• Creating Features — write your first description
• Working with the Agent — guide the agent during a feature
• Guide for Engineers — your daily workflow