Project Configuration

Project Overview

Name: E-commerce Platform
Tech Stack: Node.js, PostgreSQL, React 18, Docker
Team Size: 5 developers
Deadline: Q4 2025

Architecture

@docs/architecture.md @docs/api-standards.md @docs/database-schema.md

Development Standards

Code Style

Use Prettier for formatting
Use ESLint with airbnb config
Maximum line length: 100 characters
Use 2-space indentation

Naming Conventions

Files: kebab-case (user-controller.js)
Classes: PascalCase (UserService)
Functions/Variables: camelCase (getUserById)
Constants: UPPER_SNAKE_CASE (API_BASE_URL)
Database Tables: snake_case (user_accounts)

Git Workflow

Branch names: feature/description or fix/description
Commit messages: Follow conventional commits
PR required before merge
All CI/CD checks must pass
Minimum 1 approval required

Testing Requirements

Minimum 80% code coverage
All critical paths must have tests
Use Jest for unit tests
Use Cypress for E2E tests
Test filenames: *.test.ts or *.spec.ts

API Standards

RESTful endpoints only
JSON request/response
Use HTTP status codes correctly
Version API endpoints: /api/v1/
Document all endpoints with examples

Database

Use migrations for schema changes
Never hardcode credentials
Use connection pooling
Enable query logging in development
Regular backups required

Deployment

Docker-based deployment
Kubernetes orchestration
Blue-green deployment strategy
Automatic rollback on failure
Database migrations run before deploy

Common Commands

Command	Purpose
`npm run dev`	Start development server
`npm test`	Run test suite
`npm run lint`	Check code style
`npm run build`	Build for production
`npm run migrate`	Run database migrations

Team Contacts

Tech Lead: Sarah Chen (@sarah.chen)
Product Manager: Mike Johnson (@mike.j)
DevOps: Alex Kim (@alex.k)

Known Issues & Workarounds

PostgreSQL connection pooling limited to 20 during peak hours
Workaround: Implement query queuing
Safari 14 compatibility issues with async generators
Workaround: Use Babel transpiler

Analytics Dashboard: /projects/analytics
Mobile App: /projects/mobile
Admin Panel: /projects/admin

CLAUDE.md Management

The 200-Line Rule

Keep CLAUDE.md under 200 lines. 60 lines is the optimal length for comprehension and retention.

Claude reads the entire file on every interaction. Longer files dilute signal — critical rules compete with boilerplate, and Claude starts to treat everything as equally important (which means nothing is).

When your CLAUDE.md exceeds 100 lines, split it.

Split Large Instructions into `.claude/rules/`

Instead of one long CLAUDE.md, use the rules directory for domain-specific instructions:

.claude/
├── rules/
│   ├── development-rules.md     # Coding standards, patterns
│   ├── testing-rules.md         # Test requirements and patterns
│   ├── documentation-rules.md   # Doc standards
│   └── security-rules.md        # Security policies
└── settings.json

Claude loads all files from .claude/rules/ automatically. Each file can be focused without bloating CLAUDE.md.

Domain-Specific Rules with `<important if>` Tags

Prevent critical rules from being lost in long files using conditional importance tags:

<important if="working with the database layer">
Always use parameterized queries. Never string-concatenate SQL.
Run explain-analyze on any new query before shipping.
</important>

<important if="deploying or running migrations">
Run `npm run migrate:dry` first. Never run migrations on production without a backup.
Check migration is reversible before running forward.
</important>

<important if="modifying authentication code">
Security review required. Tag a second engineer for review on any auth PR.
</important>

These tags signal to Claude that the enclosed rules apply only in specific contexts, preventing the “wall of text” problem where all rules blur together.

Monorepo: Multiple CLAUDE.md Files

Use ancestor + descendant loading for monorepos:

Root CLAUDE.md: global rules — applies everywhere in the repo
packages/api/CLAUDE.md: API-specific rules — only loaded when working in packages/api/
packages/ui/CLAUDE.md: frontend rules — only loaded in the UI package

Claude loads all applicable CLAUDE.md files when working in a directory, with more specific (deeper) files taking precedence.

Tip: Use the root CLAUDE.md for cross-cutting concerns (security, commit format) and package-level files for technology-specific conventions (React patterns, database access).