3 min read
Feature Brief
When your project is past the initial setup and you want to add a major feature, write a brief first. This helps Claude understand what you want without a long back-and-forth. Paste this into your prompt or add it to your CLAUDE.md.
Blank Template
## Feature: [Name]
### What it does
[Describe the feature from the user's perspective. What can they do that they couldn't before?]
### How it works
1. [User does X]
2. [They see Y]
3. [Result is Z]
### What it affects
- Screens/views: [list which screens change or are new]
- Data: [what data does this feature need? does it need to be saved?]
- Navigation: [any new pages, tabs, or routes?]
### Design reference
- [Describe the look, or reference a product: "like Notion's sidebar" or "like Apple Notes"]
- [Key visual details: colors, layout, animation]
### What already exists
- [What's built that this feature connects to]
- [Any constraints: "don't change the header" or "keep the existing color scheme"]
### Out of scope
- [What this feature should NOT do — helps prevent scope creep]Filled Example
Here’s what a completed brief looks like for adding dark mode to a weather app.
## Feature: Dark Mode
### What it does
Users can switch the entire app to a dark color scheme. Easier on the eyes at night and matches system-level dark mode on macOS and iOS.
### How it works
1. User clicks the sun/moon toggle in the top-right corner of the header
2. The entire interface transitions to dark colors with a smooth 200ms fade
3. Their preference is saved to localStorage so it persists across sessions
### What it affects
- Screens/views: All screens — forecast view, hourly detail, settings page, and the onboarding flow
- Data: One stored preference (`theme: "light" | "dark"`) saved to localStorage
- Navigation: No new pages or routes. The toggle lives in the existing header bar
### Design reference
- Similar to Apple Weather's dark appearance — deep gray backgrounds, not pure black
- Use semantic color tokens: `--bg-primary`, `--bg-secondary`, `--text-primary`, `--text-secondary`, `--border`
- Light mode values: white backgrounds, gray-900 text
- Dark mode values: gray-900 backgrounds, gray-100 text
- Weather icons should remain full-color in both modes
- Cards get a subtle 1px border in dark mode (gray-700) instead of the light mode shadow
### What already exists
- The app uses CSS custom properties for spacing but has hardcoded color values
- Header component is already built — the toggle goes to the right of the city name
- Keep the existing layout and font sizes. Only colors change
### Out of scope
- Don't add a system-preference auto-detect yet — just a manual toggle for now
- Don't create a custom theme picker or accent color options
- Don't restyle third-party chart libraries in this pass