CLAUDE.md Coding Standards: A Practical Template

A CLAUDE.md coding standards section tells Claude Code exactly how your team writes code: naming conventions, file structure rules, test requirements, and the things it must never do without asking. Vague standards like "write clean code" give Claude Code nothing to check against. Specific standards like "use camelCase for function names, PascalCase for types, and SCREAMING_SNAKE_CASE for constants" produce consistent results.

Tools like fenbs are a natural place for the decisions behind those standards — why the team chose a particular naming convention, which library was preferred after a discussion, what lessons came from a past refactor. Your CLAUDE.md carries the rules; fenbs carries the reasoning and the lessons that earned them.

What makes a coding standard useful in CLAUDE.md

A standard is useful in CLAUDE.md when it describes something Claude Code can apply in the moment, without needing to look it up or make a judgment call. Compare these two versions of the same rule:

• Weak: "Write readable variable names." — Claude Code interprets "readable" differently in each session.
• Strong: "Variable names use camelCase. Boolean variables start with is, has, or can: isLoading, hasError, canEdit." — Claude Code applies this without ambiguity.
• Weak: "Tests should cover the main cases." — Too vague to act on consistently.
• Strong: "Every public function has at least one test. Tests are in __tests__/ alongside the source file, named [file].test.ts." — Claude Code knows exactly what to check.

The goal is a rule Claude Code can check against a specific piece of code it just wrote. If the rule requires judgment that only your team has, it belongs in a decision in fenbs rather than in a CLAUDE.md instruction.

The goal is not a long list of every rule your team follows. A useful CLAUDE.md coding standards section has ten to fifteen specific rules that cover the things your linter misses and the patterns that cause the most friction when they are inconsistent. Start with the rules your team most often has to correct in code review, and add others as you find gaps.

What belongs in CLAUDE.md versus a linter

Before writing a rule in CLAUDE.md, ask whether a linter already enforces it. ESLint, Prettier, mypy, and similar tools catch formatting and structural issues automatically. Rules that your linter already covers do not need to be in CLAUDE.md — Claude Code will see the linter error if it violates them.

CLAUDE.md is the right place for standards that are above the linter: naming conventions for your domain objects, architectural rules about which packages may import from which, decisions about when to add a comment versus refactor, and the behavioral rules no linter can check. Keep the file focused on what the linter misses.

The template

Copy the coding standards section below into your existing CLAUDE.md or use it as a starting point for a new one. Remove sections that your linter already covers, and adapt the examples to your language and framework.

## Coding standards

### Naming
- Functions and variables: camelCase (`getUserById`, `isActive`)
- Types, classes, and components: PascalCase (`UserProfile`, `ApiError`)
- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRIES`, `DEFAULT_TIMEOUT_MS`)
- Boolean variables start with `is`, `has`, or `can`: `isLoading`, `hasPermission`
- Files: kebab-case for modules (`user-profile.ts`), PascalCase for components (`UserProfile.tsx`)

### File structure
- One export per file for components and services.
- Tests live in `__tests__/` next to the source file, named `[file].test.ts`.
- Types shared across modules live in `src/types/`; local types stay in the file that uses them.

### Imports
- Use absolute imports from `@/` for project code, relative imports only within the same folder.
- No circular imports. If two files need to import each other, extract the shared type or function.

### Functions and components
- Functions are small: one responsibility, named to describe that responsibility.
- No function longer than [your threshold] lines. Split it instead of adding a comment.
- No magic numbers: extract named constants.

### Error handling
- Errors are handled where they can be acted on, not swallowed silently.
- User-facing error messages do not include stack traces or internal identifiers.
- Log the underlying error for debugging; show the user a plain message.

### Tests
- Every public function has at least one test.
- Tests verify behavior, not implementation: test what the function does, not how it does it.
- Run the full test suite before committing. All tests must pass.

### What Claude Code must not do without asking
- Remove an existing test.
- Add a dependency that is not already in the package file.
- Change a public API surface (function signatures, exported types, route paths).

Architectural rules need special treatment

Architectural rules — which layer may call which, which packages are permitted in which module, how side effects are isolated — are some of the most important constraints to document. They are also the hardest to enforce with a linter. An explicit rule like "API handlers call service functions only; service functions do not import from API handlers" gives Claude Code a clear boundary it can respect.

When the team changes an architectural decision — switching from a three-layer to a two-layer structure, adopting a new state management approach — the old rule should be replaced in CLAUDE.md, and the new decision recorded in fenbs with the reason for the change. A future session can then understand both the current rule and the history behind it.

Decisions and lessons behind the standards

Many coding standards come from hard experience: the naming convention that was adopted after a confusing incident, the test requirement that caught a pattern of regressions, the import rule that emerged after a circular dependency was difficult to untangle. Those stories are not noise — they explain why the rule matters and help a future team member (or AI assistant) understand when to question it.

How to do this with fenbs

1. Create a free account. Start a project for your codebase and add the current tasks.
2. Record the key architectural decisions — why you chose the current structure, which library debates were settled — as Decisions and rules in fenbs.
3. Copy the coding standards template above into your CLAUDE.md, remove sections your linter covers, and adapt the examples to your language.
4. Connect Claude Code to fenbs from Integrations. Ask it to read the project context so it has both the file-level rules and the team decisions before coding.
5. When a standard changes, update CLAUDE.md and record the reason in fenbs as a new decision that supersedes the old one.

For more context on how to structure a full CLAUDE.md, see CLAUDE.md examples. For troubleshooting when Claude Code ignores an instruction, see CLAUDE.md not working.