Skip to content
Caracal

Code Style

Caracal enforces a uniform set of code standards across all languages and packages. These rules are codified in .claude/rules/ at the repository root and are applied to every source file.

File headers

Section titled “File headers”

Every source file must begin with the copyright header, adapted to the file’s comment syntax:

TypeScript / JavaScript:

// Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
// Caracal, a product of Garudex Labs
//
// One-sentence description of what this file is.

Go:

// Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
// Caracal, a product of Garudex Labs
//
// One-sentence description of what this file is.

Python:

# Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
# Caracal, a product of Garudex Labs
#
# One-sentence description of what this file is.

MDX (docs pages — frontmatter only, no comment header):

MDX files use frontmatter as their header. Do not add a comment block before ---. The title and description frontmatter fields serve as the file descriptor.

Rules for the header:

  • Two spaces after All Rights Reserved. — exact spacing is required.
  • Blank line between the copyright block and the description.
  • Description is a single sentence, present tense, describing what the file is — not what it does, not why it exists.
  • No metadata, version notes, or author lines inside the header block.

Naming conventions

Section titled “Naming conventions”
RuleExample
Variables and functions: CamelCasetokenCache, exchangeToken
Types and classes: PascalCaseTokenClaims, OPAEngine
Files and directories: camelCase or kebab-case matching surrounding conventiontokenCache.ts, token-cache.go
Go exported identifiers: PascalCasefunc NewKeyCache(...)
Python modules: snake_casetoken_state.py
Constants: UPPER_SNAKE in Python; CamelCase in Go and TSAUDIT_HMAC_KEY, MaxGrantTTL

Forbidden prefixes: new_, fixed_, updated_, old_, or similar mutation-history prefixes. Go constructor functions named NewX are exempt.

Forbidden in names: - (hyphen). Use _ only when the language requires it (Python module files, test fixtures).

Match the naming pattern in the surrounding code. If an existing file uses a convention that differs from the above, match what is already there.

Comments

Section titled “Comments”

Write comments only when the why is non-obvious — a hidden constraint, a subtle invariant, a workaround for a known bug, behavior that would surprise a reader.

Do not write comments that:

  • Restate what the code already expresses through clear identifiers.
  • Reference the current task, fix, issue number, or PR.
  • Describe what was changed, removed, or added.
  • Say “previously”, “now”, “added for”, “used by”.

One short line is the maximum for inline comments. Do not write multi-paragraph docstrings or multi-line comment blocks for internal code. Public API documentation (Go godoc, TypeScript JSDoc) is the exception — keep it concise and accurate.

instructions.md files

Section titled “instructions.md files”

Every non-trivial directory that contains logic or structure must have exactly one instructions.md file. The file covers only the directory it lives in.

Required structure:

  1. First bullet: scope of the directory.
  2. Required rules (using must, must not, only).
  3. Forbidden rules.

instructions.md files must not duplicate rules from parent directories, include pseudocode, or use weak language (should, consider, prefer).

When you add a new directory with meaningful structure, create its instructions.md. When you change the naming patterns or conventions for a directory, update the instructions.md immediately. Delete or rewrite instructions that no longer match the actual code.

Only root/README.md and files under docs/ may be .md files outside of instructions.md. Do not create README.md inside packages/, services/, or any subdirectory — use instructions.md instead.

No-legacy rule

Section titled “No-legacy rule”

The repository enforces a strict no-legacy policy:

  • Each feature has exactly one execution path. There are no fallback paths, compatibility shims, or version-conditional branches.
  • Remove deprecated functions, classes, or modules when the replacement lands — do not keep them “just in case”.
  • Remove feature flags that gate old vs. new behavior once the new behavior is the only behavior.
  • Remove dead code, commented-out blocks, and unused abstractions.
  • Do not layer a new implementation on top of an existing one. Rewrite the affected area cleanly.
  • Do not add migration helpers unless a migration is explicitly required right now.

When you encounter legacy code while working on a change, remove it as part of the same PR rather than leaving it for later.

Product isolation

Section titled “Product isolation”

The caracal/ and caracalEnterprise/ directories are separate products with a hard boundary:

  • Do not import, require, or reference source files across the two roots.
  • Do not copy or mirror implementation code from one product into the other.
  • Shared behavior crosses the boundary only through explicitly approved, license-compliant interfaces.

Local service ports must also be isolated: caracal/ and caracalEnterprise/ services use non-overlapping port assignments so both stacks can run side by side.