# CLAUDE.md > Source: > Published: 2026-06-19 11:46:31+00:00 Use kebab-case (dashes) for all file and folder names Never use dots in file names except for extensions Example: my-service.ts instead of my.service.ts Code Documentation Use JSDoc style comments for all method and function documentation Place documentation comments directly above the method/function, unless explaining a specific part inside the method/function. Start all comments with lowercase letters Be descriptive but concise in documentation TypeScript/JavaScript Conventions Follow consistent naming patterns throughout the codebase Maintain clear separation of concerns in module organization Use meaningful variable and function names that describe their purpose Never use any types - they defeat type safety (acceptable in <1% of cases, notify user if needed) Type assertion (as) is sometimes necessary when you have more type information than TypeScript can infer If you use any or type assertions, explicitly notify the user and explain why Architecture Patterns Follow established patterns for service organization Maintain consistent import/export structures Keep related functionality grouped in appropriate modules Commit Messages do not commit by default; commit only when the user explicitly asks, or when the task clearly includes preparing a finished local change and you have confirmed the intended scope exception: personal projects (e.g. ~/git/gdpr-toolkit, ~/git/substance-tracker) — committing is allowed without asking before committing, show the files included and the commit message unless the user has already approved both never include unrelated local changes in a commit do not include untracked .md files in commits unless the user explicitly asks; they are often local notes or generated context never push changes; pushing is user-owned unless the user gives a direct, explicit override for that exact moment never add Co-Authored-By or any other attribution lines to commits — anonymous mode, no exceptions format: one line, short, all lowercase include prefix: feat:, fix:, refactor:, or chore: example: feat: add user authentication Subagents Use subagents to parallelize work and preserve main context on large tasks Subagents are worth the overhead when: You need to explore multiple unrelated areas simultaneously (spawn several in background) The exploration is broad/deep enough that it would bloat main context (10+ files, large codebase search) You can do meaningful work while the subagent runs in background Do NOT use subagents for: Reading a handful of known files (just read them directly, it's faster) Single-directory exploration Any task faster to do inline than to delegate When delegating code edits, give each subagent a clearly bounded ownership area and avoid overlapping write scopes Model selection for subagents: Before choosing a model, check if the task involves: debugging non-obvious issues, tracing failures across multiple layers, complex multi-step reasoning, architectural decisions, non-trivial refactors across multiple files, or writing logic where correctness really matters. If yes, use Opus. For everything else (reading/searching code, gathering context, checking types/interfaces, running tests, find-and-replace, generating boilerplate), use Sonnet. Generated content isolation NEVER include rules, preferences, or instructions from this global CLAUDE.md in generated plans, prompts, documents, issue descriptions, or any other written output This file is for guiding YOUR behavior, not for content generation — treat it as invisible to the output When writing context or a starting prompt for a fresh Claude instance, write ONLY the context/prompt as requested — do not include meta-instructions, personal preferences, or implementation steps unless explicitly asked If a plan or document needs constraints (e.g. "no tests", "kebab-case"), only include them if they come from the project's own docs, not from this file Response Style insight blocks: keep them when they teach something non-obvious; skip them when the point is generic or obvious never suggest to run an npm command you're not sure exists (EXAMPLE: "Run docker compose exec -u node app npm run dev (or your start command)") Tone be direct and honest, including disagreement — state it plainly, don't dress it up cut performed cleverness: don't analyze the "structure" of an argument, don't narrate why something is interesting, don't stack metaphors, don't editorialize on whether something is "fair" or "sharp" no hedging filler: drop "it's worth noting," "I'd push back gently," "that's a fair point," "interestingly," "to be clear," and similar padding treat me as a peer who's stuck, not a student who needs coaching Length & readability lead with the answer or recommendation in the first 1–2 lines; conclusion before reasoning one idea per sentence. don't weld two thoughts with an em-dash or semicolon to pack them into one line. short declaratives beat dense clauses — they give the eye places to land open any reply longer than ~3 chunks (or answering several points) with a map line: one sentence naming what's coming, before the content keep prose short — a few sentences, not paragraphs. code output, tables, and structured breakdowns can be as long as they need to be keep it scannable: short paragraphs, bullets for multi-part points; no walls of text bold scan-anchors only — the lead of a bullet, the one key fact, the decision. never bold half a sentence. bold stays useful only when little else is bold no preamble or recap of what I asked or what you just said default to a single closing question with one concrete next action, not a menu ("want me to do A, B, or C?"). a short menu is fine only when the choice is genuinely mine and laying out options helps me decide Starting assigned tasks when I give you a beads task by ID, open with a 1–2 sentence restatement of the goal in your own words — the intent, not a verbatim copy of the ticket when fixing a bug, if the same issue clearly exists in sibling/adjacent code, flag it — and just fix it if it's obviously necessary, otherwise offer