CONTEXT.md Template

# CONTEXT.md

## What AI Needs to Know

### Your Background
**Your experience level:** [Beginner / Intermediate / Advanced in design/coding]
**Your familiarity with:** [Git / React / CSS / etc.]
**Your working style:** [Prefer detailed explanations / Just give me the code / etc.]

### Project Context
**Why this project matters:** [Personal project / Client work / Portfolio piece / Learning]
**Timeline pressure:** [Urgent deadline / Relaxed learning / etc.]
**Who will see this:** [Just you / Client / Public / Potential employers]

### Communication Preferences
**When AI suggests code:**
- [ ] Explain what it does line by line
- [ ] Just show me the code
- [ ] Show code + brief summary

**When something breaks:**
- [ ] Walk me through debugging step by step
- [ ] Tell me the fix and why
- [ ] Just give me the working code

**Level of detail:**
- [ ] Beginner - Explain everything including basic concepts
- [ ] Intermediate - Skip basics, explain complex parts
- [ ] Advanced - Minimal explanation, focus on implementation

### Technical Environment
**Operating System:** [Mac / Windows / Linux]
**Code Editor:** [VS Code / Cursor / etc.]
**Terminal:** [Built-in / iTerm / etc.]
**Node version:** [Run: `node --version`]
**Git installed:** [Yes / No / Not sure]

### Current Roadblocks
[If you're stuck on something specific, describe it here so AI context carries forward]

### AI Do's and Don'ts for This Project
**Always:**
- [e.g., "Use Tailwind classes, not custom CSS"]
- [e.g., "Test on mobile first"]
- [e.g., "Commit after each working feature"]

**Never:**
- [e.g., "Don't use any external APIs"]
- [e.g., "Don't add animations unless I ask"]
- [e.g., "Don't install new packages without asking first"]

### Design Constraints
**Must have:**
- [e.g., "Accessible to WCAG AA standards"]
- [e.g., "Works on IE 11" (if required)]
- [e.g., "Loads in under 3 seconds"]

**Nice to have:**
- [e.g., "Smooth animations"]
- [e.g., "Dark mode"]
- [e.g., "Offline support"]

Example: Beginner Designer Context

# CONTEXT.md

## What AI Needs to Know

### Your Background
**Your experience level:** Beginner in coding, 5 years in design (Figma, Sketch)
**Your familiarity with:**
- ✅ HTML/CSS basics
- ⚠️ Some JavaScript (can read it, struggle to write it)
- ❌ Git (know what it is, never used it)
- ❌ React (heard of it, don't understand it yet)
- ✅ Tailwind (used it once, liked it)

**Your working style:** I prefer explanations first, then code. I learn better when I understand WHY, not just WHAT.

### Project Context
**Why this project matters:** Portfolio piece to showcase my design + coding skills for job applications. Want to prove I can translate my designs into working code.

**Timeline pressure:** Moderate - have 2 weeks before job interview, but want to get it done in 1 week to have buffer for feedback.

**Who will see this:** Potential employers at tech companies (engineers + design managers).

### Communication Preferences
**When AI suggests code:**
- [x] Explain what it does line by line (at least for complex parts)
- [ ] Just show me the code
- [x] Show code + brief summary

**When something breaks:**
- [x] Walk me through debugging step by step
- [ ] Tell me the fix and why
- [ ] Just give me the working code

**Level of detail:**
- [x] Beginner - Explain everything including basic concepts (especially Git!)
- [ ] Intermediate - Skip basics, explain complex parts
- [ ] Advanced - Minimal explanation, focus on implementation

### Technical Environment
**Operating System:** Mac (macOS Sonoma 14.2)
**Code Editor:** VS Code (just installed)
**Terminal:** Built-in Mac Terminal
**Node version:** v20.10.0
**Git installed:** Yes (came with Xcode)

### Current Roadblocks
- Confused about when to commit in Git (every change? once per hour? when feature works?)
- Not sure how to structure project folders (where do images go? styles?)
- Nervous about deploying to Vercel (never done it before)

### AI Do's and Don'ts for This Project
**Always:**
- Use Tailwind CSS (I'm familiar with it)
- Explain Git commands before I run them
- Show me how to test on mobile (Chrome DevTools?)
- Create save points (Git commits) after each working feature
- Warn me before making big changes to file structure

**Never:**
- Don't use jQuery or other old libraries
- Don't install packages without explaining what they do
- Don't assume I know how to deploy (walk me through it)
- Don't use complex React patterns unless necessary (keep it simple!)

### Design Constraints
**Must have:**
- Mobile-first (works perfectly on iPhone)
- Fast loading (under 3 seconds on 4G)
- Accessible (keyboard navigation, screen reader friendly)
- Clean, minimal design (let work speak for itself)

**Nice to have:**
- Smooth scroll animations
- Dark mode (maybe v2?)
- Interactive project filters

Example: Experienced Designer Context

# CONTEXT.md

## What AI Needs to Know

### Your Background
**Your experience level:** Advanced designer, intermediate coder
**Your familiarity with:**
- ✅ React (built 5+ projects)
- ✅ Git (use it daily)
- ✅ Tailwind (preferred CSS framework)
- ✅ Next.js (basic knowledge)
- ⚠️ TypeScript (can read it, rusty at writing)

**Your working style:** Show me the code with minimal explanation. I'll ask if I don't understand.

### Project Context
**Why this project matters:** Client project for startup - analytics dashboard for their internal team. Budget is tight so building myself rather than hiring dev.

**Timeline pressure:** High - promised beta in 2 weeks, they're already testing with spreadsheets.

**Who will see this:** 10-person startup team (non-technical users).

### Communication Preferences
**When AI suggests code:**
- [ ] Explain what it does line by line
- [x] Just show me the code
- [x] Show code + brief summary (only for complex logic)

**When something breaks:**
- [ ] Walk me through debugging step by step
- [x] Tell me the fix and why
- [ ] Just give me the working code

**Level of detail:**
- [ ] Beginner - Explain everything including basic concepts
- [x] Intermediate - Skip basics, explain complex parts
- [ ] Advanced - Minimal explanation, focus on implementation

### Technical Environment
**Operating System:** Mac (macOS Sonoma)
**Code Editor:** Cursor
**Terminal:** iTerm2
**Node version:** v20.10.0
**Git installed:** Yes

### Current Roadblocks
- Need to integrate with their existing API (REST, documented but inconsistent)
- Performance concerns: they have 100K+ rows of data, worried about table rendering
- Don't want to over-engineer but need it to be maintainable

### AI Do's and Don'ts for This Project
**Always:**
- Use TypeScript (trying to get better at it)
- Add loading and error states (users are impatient)
- Consider mobile layout (they often check on phones)
- Use React Query for API calls (heard it's good for this)

**Never:**
- Don't install heavy charting libraries (bundle size matters)
- Don't add animations unless they're subtle and fast
- Don't create unnecessary abstractions (keep it simple)

### Design Constraints
**Must have:**
- Works on Chrome (their whole team uses it)
- Loads large datasets without freezing
- Exports to CSV (they requested this specifically)

**Nice to have:**
- Real-time updates (WebSocket)
- Custom date range picker
- Dashboard customization (drag/drop widgets)