Claude Code Standards

A structured repository of coding standards, conventions, and guidelines for use with Claude Code.

This repository defines how Claude should behave when writing, reviewing, or reasoning about code. It serves as the authoritative source for project conventions, code quality expectations, and non-negotiable rules.

---

🎯 Purpose

Claude Code reads markdown files in your project to understand your preferences and standards. This repository:

• Centralizes standards across all your projects
• Reduces context repetition by referencing established guidelines
• Ensures consistency in Claude's code generation and recommendations
• Documents decisions so they don't need to be re-explained

---

📁 Repository Structure

claude-standards/
├── CLAUDE.md                    # Main entry point - references all standards
├── README.md                    # This file
└── standards/
    ├── commits.md               # Commit message conventions (Conventional Commits)
    ├── code-quality.md          # Universal code quality principles
    ├── frontend.md              # React/Next.js specific standards
    ├── backend.md               # Node.js/API specific standards
    ├── testing.md               # Testing philosophy and patterns
    └── security.md              # Security requirements and practices

---

⚙️ How It Works

1. Main Guidelines (CLAUDE.md)

The root CLAUDE.md file is your primary directive for Claude. It defines:

• Engineering philosophy and communication principles
• Tech stack constraints
• Non-negotiable rules that apply everywhere
• References to detailed standards documents

Claude reads this first and uses it as the authoritative source when conflicts arise.

2. Standards Directory

The standards/ folder contains modular, focused documents for specific domains:

File	Purpose	Key Content
commits.md	Commit conventions	Conventional Commits format, scope rules, examples
code-quality.md	Universal code principles	Structure, naming, error handling, type safety
frontend.md	React/Next.js rules	Component design, hooks, state management, performance
backend.md	Node.js/API rules	API design, validation, async patterns, database
testing.md	Testing standards	What to test, test structure, mocking policy
security.md	Security requirements	Secrets management, input validation, auth patterns

---

📖 Usage

Primary Setup: Global Reference

Add this reference to your global ~/.claude/CLAUDE.md:

# Global Claude Code Guidelines

For coding standards: ~/Documents/REPOS/claude-standards/CLAUDE.md

This makes the standards available across all your projects automatically.

Project-Specific Overrides

Individual projects can have their own CLAUDE.md to override or extend the global standards:

# MyApp Guidelines

## Project-Specific Overrides

- API: GraphQL (not REST)
- Database: PostgreSQL with Prisma ORM
- Deployment: Vercel
- Styling: Tailwind CSS

## Additional Context

This is a greenfield project prioritizing rapid iteration over comprehensive testing.

How Claude Reads This

1. Global ~/.claude/CLAUDE.md → References this repo
2. This repo's CLAUDE.md → References standards files
3. Project's CLAUDE.md → Project-specific overrides

Precedence: Project-specific > This repo > Global defaults

Referencing Specific Standards

When you need Claude to follow a specific standard in conversation:

"Use the commit standards" "Follow the backend API format from standards"

Claude will reference the appropriate file from this repo.

---

🚀 Quick Start

Step 1: Set up global reference

Add to ~/.claude/CLAUDE.md:

# Global Claude Code Guidelines

For coding standards: ~/Documents/REPOS/claude-standards/CLAUDE.md

Step 2: (Optional) Add project-specific overrides

In any project's CLAUDE.md, document only what's different:

# MyApp Guidelines

- Database: Supabase
- Auth: Clerk
- Styling: Tailwind

Step 3: Work normally

Claude will automatically apply:

1. Standards from this repo (via global reference)
2. Project-specific overrides (if present)

That's it. No need to repeat standards in every project.

---

🛠️ Tech Stack

These standards assume:

• Languages: TypeScript (primary), Python (scripting/backend)
• Frontend: React with function components and hooks
• Runtime: Node.js
• Package Manager: pnpm (preferred)
• Validation: Zod schemas
• Testing: Jest/Vitest + React Testing Library

If your stack differs, document deviations in your project's CLAUDE.md.

---

🤝 Contributing

This is a personal standards repository. If you're collaborating:

1. Discuss changes before editing shared standards
2. Use conventional commits for changes
3. Update documentation when patterns change
4. Keep standards focused and actionable

---

📄 License

Personal use. Adapt as needed for your own projects.