AI Vibe 03 — Repo & Context Management

An AI model has no knowledge of your specific codebase unless you provide it. Without context, it generates generic solutions that may:

• Use the wrong framework version or pattern for your project
• Ignore naming conventions your team follows
• Duplicate utilities that already exist in your codebase
• Suggest approaches you've already decided against

These files sit in your project root and are automatically loaded by Claude Code and Cursor as persistent instructions. They act as a standing system prompt for every AI interaction in your project.

# CLAUDE.md — for Claude Code
# .cursorrules — for Cursor IDE
# (Both use similar markdown format)

# Project: MedStore Web App
# Stack: Vue 3 + TypeScript, Laravel 11 API, Tailwind CSS

## Tech Stack
- Frontend: Vue 3, Pinia, Vue Router, Tailwind CSS
- Backend: Laravel 11, Sanctum, MySQL 8
- Testing: Vitest (frontend), PHPUnit (backend)
- Deployment: Laravel Forge + Nginx

## Conventions
- Vue components: PascalCase, Composition API only
- Composables: use prefix, e.g. useAuth, useCart
- API calls: through /src/api/ service files, never in components
- Env vars: VITE_ prefix for frontend, no .env in git

## Do NOT
- Use Options API
- Use inline styles (always Tailwind)
- Import lodash (use native JS)
- Use any deprecated Laravel features

# Example folder structure section in CLAUDE.md:
## Project Structure
src/
  api/         # Axios service files (one per domain)
  components/  # Reusable UI components
  composables/ # Vue composables (use prefix)
  pages/       # Page-level components (route targets)
  stores/      # Pinia stores
  types/       # TypeScript interfaces and types

## Key Files
src/api/auth.ts       # Auth API calls
src/stores/auth.ts    # Auth Pinia store
src/composables/useApi.ts  # Base Axios composable with auth header

When asking AI to work on a specific task, paste only the files relevant to that task — not the whole codebase.

# When asking about a cart feature, share:
- The Pinia cart store
- The CartItem component
- The relevant API service file
# Do NOT paste: auth store, user profile, unrelated pages

# Template for sharing context in a prompt:
"Here are the relevant files for this task:

--- src/stores/cart.ts ---
[paste file contents]

--- src/api/orders.ts ---
[paste file contents]

Now: add a coupon code field to the cart store that
calls /api/validate-coupon and applies the discount."

Your git history and branch names communicate intent to both humans and AI tools.

# Meaningful commit messages help AI understand what changed:
git log --oneline
# Good:
a1b2c3 feat: add product search with debounce composable
d4e5f6 fix: cart total not recalculating after item removal
g7h8i9 refactor: extract API error handling to useApiError

# Bad:
a1b2c3 update
d4e5f6 fix bug
g7h8i9 changes

# Meaningful branch names:
feature/cart-coupon-codes
fix/checkout-validation-error
refactor/product-api-layer

# Claude Code can read your git log — the more descriptive
# your history, the better context it has for your codebase.

Claude Code Memory

# Claude Code reads CLAUDE.md automatically from:
~/.claude/CLAUDE.md          # Global (all projects)
/your/project/CLAUDE.md      # Project-level
/your/project/src/CLAUDE.md  # Directory-level (rare)

# To add a memory during a session:
/memory "Always use axios.create() instance from src/api/client.ts"
# Writes to CLAUDE.md for future sessions

Cursor Rules

# .cursorrules in project root
# Supports glob-based rules for different file types:
---
name: Vue Components
globs: ["src/components/**/*.vue"]
rules:
  - Use Composition API with script setup
  - Props must have TypeScript types
  - Emit events must be defined with defineEmits

---
name: API Services
globs: ["src/api/**/*.ts"]
rules:
  - Use the axios instance from src/api/client.ts
  - All functions must be async
  - Handle errors and return typed responses

• Start fresh for unrelated tasks — old context from a different feature can mislead AI
• Update CLAUDE.md when patterns change — if you adopt a new convention, document it immediately
• Token limits are real — Claude has a large context window, but very large files still slow things down; summarize long files when possible
• Relevance over completeness — a 20-line excerpt of the right file beats pasting the 200-line full file
• Refresh context in long sessions — if a conversation goes on for a long time, re-paste the key file at the top of a new message
• Version your CLAUDE.md — commit it to git so the whole team benefits from project context

# Quick context refresh template:
"Reminder of project context:
- Stack: Vue 3 + Laravel 11 + Tailwind
- No Options API, no inline styles
- See src/stores/auth.ts for auth pattern

Now: [your actual task here]"