Understanding Context
The CLAUDE.md file is the heart of Bootspring. It's an automatically generated context file that helps your AI assistant understand your project instantly.
What is CLAUDE.md?#
CLAUDE.md is a markdown file that contains everything your AI assistant needs to know about your project:
- Project type and purpose
- Tech stack and frameworks
- File structure and conventions
- Available commands
- Development guidelines
- Custom instructions
When your AI assistant reads this file, it can provide tailored guidance specific to your project.
How Context Generation Works#
When you run bootspring init or bootspring generate, Bootspring:
- Scans your project for configuration files
- Detects your tech stack from dependencies
- Analyzes project structure to understand organization
- Reads existing configs (tsconfig, eslint, etc.)
- Generates CLAUDE.md with comprehensive context
Your Project Bootspring AI Assistant
│ │ │
│ package.json │ │
│ tsconfig.json ────────> │ Analyze & Generate │
│ src/ │ │ │
│ ... │ ▼ │
│ │ CLAUDE.md ────────────> │ Understands
│ │ │ Your Project
CLAUDE.md Structure#
A typical CLAUDE.md file contains these sections:
1# Project Name
2
3## Overview
4Brief description of what the project does.
5
6## Tech Stack
7- Framework: Next.js 14
8- Language: TypeScript
9- Database: PostgreSQL with Prisma
10- Styling: Tailwind CSS
11- Testing: Vitest, Playwright
12
13## Project Structure
14├── app/ # Next.js app router
15├── components/ # React components
16├── lib/ # Utility functions
17├── prisma/ # Database schema
18└── tests/ # Test files
19
20## Key Files
21- `app/layout.tsx` - Root layout
22- `lib/db.ts` - Database client
23- `lib/auth.ts` - Authentication utilities
24
25## Commands
26- `npm run dev` - Start development server
27- `npm run build` - Build for production
28- `npm run test` - Run tests
29- `npm run lint` - Run linter
30
31## Development Guidelines
321. Use TypeScript for all new code
332. Follow the existing component patterns
343. Write tests for new features
354. Use Prisma for database access
36
37## Bootspring Configuration
38- Agents: frontend-expert, backend-expert, database-expert
39- Quality gates: pre-commit, pre-push
40- Skills: Tailwind, Prisma patternsAutomatic Detection#
Bootspring automatically detects many aspects of your project:
Framework Detection#
| Files Detected | Framework Identified |
|---|---|
next.config.js, app/ | Next.js (App Router) |
next.config.js, pages/ | Next.js (Pages Router) |
vite.config.ts | Vite |
gatsby-config.js | Gatsby |
remix.config.js | Remix |
nuxt.config.ts | Nuxt |
angular.json | Angular |
svelte.config.js | SvelteKit |
Database Detection#
| Files Detected | Database Identified |
|---|---|
prisma/schema.prisma | Prisma |
drizzle.config.ts | Drizzle |
typeorm.config.ts | TypeORM |
mongoose in package.json | MongoDB/Mongoose |
Testing Detection#
| Files Detected | Framework Identified |
|---|---|
vitest.config.ts | Vitest |
jest.config.js | Jest |
playwright.config.ts | Playwright |
cypress.config.ts | Cypress |
Customizing Context#
Custom Sections#
Add custom sections in bootspring.config.js:
1// bootspring.config.js
2module.exports = {
3 context: {
4 customSections: [
5 {
6 title: 'API Conventions',
7 content: `
8 - All endpoints return JSON
9 - Use camelCase for field names
10 - Include pagination for list endpoints
11 - Return 201 for created resources
12 `,
13 },
14 {
15 title: 'Component Guidelines',
16 content: `
17 - Use PascalCase for component names
18 - One component per file
19 - Co-locate tests with components
20 - Use composition over inheritance
21 `,
22 },
23 {
24 title: 'Git Workflow',
25 content: `
26 - Use conventional commits
27 - Squash merge to main
28 - Require PR reviews
29 `,
30 },
31 ],
32 },
33};Excluding Files#
Exclude sensitive or irrelevant files:
1// bootspring.config.js
2module.exports = {
3 context: {
4 exclude: [
5 'node_modules/**',
6 '.git/**',
7 'dist/**',
8 'build/**',
9 'coverage/**',
10 '.env*',
11 '*.log',
12 '*.lock',
13 ],
14 },
15};Including Additional Files#
Explicitly include important files:
1// bootspring.config.js
2module.exports = {
3 context: {
4 include: [
5 'docs/ARCHITECTURE.md',
6 'docs/API.md',
7 '.github/CONTRIBUTING.md',
8 ],
9 },
10};Regenerating Context#
Context should be regenerated when your project changes significantly.
Manual Regeneration#
bootspring generateOr ask your AI assistant:
Regenerate the CLAUDE.md context file.
Automatic Regeneration#
Enable auto-regeneration in config:
1// bootspring.config.js
2module.exports = {
3 context: {
4 autoGenerate: true,
5 watchPatterns: [
6 'package.json',
7 'tsconfig.json',
8 'prisma/schema.prisma',
9 ],
10 },
11};When to Regenerate#
Regenerate your context when:
- Adding new dependencies
- Changing project structure
- Updating configuration files
- Adding new features
- Modifying coding conventions
- Onboarding new team members
Context Best Practices#
1. Keep It Current#
Outdated context leads to outdated advice. Regenerate regularly:
# Add to your workflow
bootspring generate && git add CLAUDE.md2. Add Team Conventions#
Include your team's specific patterns:
1// bootspring.config.js
2module.exports = {
3 context: {
4 customSections: [
5 {
6 title: 'Team Conventions',
7 content: `
8 - We use Tailwind CSS, never inline styles
9 - All API calls go through lib/api.ts
10 - State management uses Zustand
11 - Forms use React Hook Form + Zod
12 `,
13 },
14 ],
15 },
16};3. Document Key Patterns#
Help the AI understand your patterns:
1// bootspring.config.js
2module.exports = {
3 context: {
4 customSections: [
5 {
6 title: 'Component Pattern',
7 content: `
8 Components follow this structure:
9
10 components/
11 ├── Button/
12 │ ├── Button.tsx # Main component
13 │ ├── Button.test.tsx # Tests
14 │ ├── Button.stories.tsx # Storybook
15 │ └── index.ts # Exports
16 `,
17 },
18 ],
19 },
20};4. Include Architecture Decisions#
Document important decisions:
1// bootspring.config.js
2module.exports = {
3 context: {
4 customSections: [
5 {
6 title: 'Architecture Decisions',
7 content: `
8 ADR-001: We use server components by default
9 ADR-002: API routes handle auth via middleware
10 ADR-003: Database access only through Prisma
11 ADR-004: No client-side data fetching in pages
12 `,
13 },
14 ],
15 },
16};How AI Assistants Use Context#
When you interact with your AI assistant, here's what happens:
- Context Loading: The assistant reads CLAUDE.md
- Understanding: It parses your tech stack, structure, and guidelines
- Tailored Response: Advice matches your specific setup
Without Context#
User: Create a button component
AI: Here's a React button component:
[Generic component with CSS classes]
With Context#
User: Create a button component
AI: Based on your Next.js + Tailwind setup, here's a button
component following your existing patterns:
[Component using your design system, TypeScript,
your naming conventions, exported correctly]
Viewing Current Context#
See what context is being used:
bootspring context showOr ask your AI:
Show me the current Bootspring context for this project.
Context and Agents#
Agents use context to provide specialized advice. The context informs:
- frontend-expert: Your UI framework and styling approach
- database-expert: Your ORM and database type
- testing-expert: Your testing framework and patterns
- security-expert: Your auth setup and security requirements
Troubleshooting#
"AI doesn't seem to understand my project"#
- Check if CLAUDE.md exists:
ls CLAUDE.md - Regenerate context:
bootspring generate - Verify it's not in .gitignore
"Context is missing my tech stack"#
Add it explicitly in config:
1// bootspring.config.js
2module.exports = {
3 stack: {
4 frontend: ['react', 'nextjs', 'tailwindcss'],
5 backend: ['nodejs'],
6 database: ['postgresql', 'prisma'],
7 },
8};"Context includes sensitive information"#
Add to exclusions:
1// bootspring.config.js
2module.exports = {
3 context: {
4 exclude: [
5 '.env*',
6 '**/secrets/**',
7 '**/credentials/**',
8 ],
9 },
10};Next Steps#
- Using Agents - Get expert help
- Using Skills - Use code patterns
- Configuration - Full config reference