claude/CLAUDE.md

Global coding preferences

Apply these preferences across all projects unless repository-specific instructions override them.

General philosophy

I prefer clean, readable, maintainable code with strong structural discipline, inspired by 42-style constraints but adapted pragmatically to each language, framework, and project.

These rules are important, but they are not absolute dogma:

• apply them by default
• report clearly when code does not follow them
• if a deviation is justified, keep it and explain why
• if a deviation is not clearly justified, ask whether it should be kept or fixed

Design principles

• Prefer simple, readable, maintainable code over clever or overly compact code.
• Each function, method, or equivalent unit should have one clear responsibility.
• Preserve existing behavior unless explicitly asked to change it.
• Avoid unrelated changes during a fix or refactor.
• Keep modifications scoped and intentional.

Function and method size

• Prefer keeping the core logic of a function or method within 25 useful lines.
• Empty lines do not count toward this limit.
• Multi-line wrapped statements count as one logical instruction for this rule.
• Error handling may extend the total size when necessary, but the main logic should remain compact and easy to understand.
• If a unit becomes too large, split it into small helpers.
• Use private/internal/file-local helpers when the language supports them.

Line length

• Prefer a maximum of 80 characters per line when reasonably possible.
• If a line is too long, split it cleanly for readability.
• Long calls, conditions, and expressions should be formatted clearly.

Parameters

• Prefer no more than 5 parameters per function or method.
• If more inputs are needed, group them into a meaningful structure adapted to the language, such as an object, record, struct, dataclass, DTO, config object, or equivalent.

Local variables

• Prefer no more than 5 local variables per function or method.
• If more local state is needed, consider:
  • splitting the logic
  • extracting a helper
  • introducing a dedicated small structure adapted to the language

Shared and global state

• Global state is discouraged.
• Prefer explicit data flow through parameters, return values, objects, context structures, dependency injection, or another justified mechanism.
• If shared or global state is used, mention it explicitly and justify it.

Comments and documentation

• Functions and methods should be documented when their purpose, parameters, return value, or intent are not immediately obvious.
• The comment should help explain intent and usage, not restate the code line by line.
• Apply the documentation style that fits the language and project conventions (docstring, block comment, JSDoc, Doxygen, XML docs, etc.).
• Internal/private helpers are not exempt if their role is unclear.

Readability

• Use explicit, consistent, and meaningful names.
• Prefer straightforward control flow.
• Simplify or extract complex conditions.
• Avoid hidden side effects unless clearly necessary.
• Prefer code that is easy to review, test, and modify.

Refactoring and modifications

• During refactoring, prioritize:
  1. safety
  2. readability
  3. consistency with the project
• Keep behavior unchanged unless explicitly asked otherwise.
• After modifying a function, feature, or behavior, verify that no residue from the previous implementation remains.
• Remove obsolete code, dead branches, unused helpers, stale flags, outdated comments, legacy conditions, and old-version leftovers when they are no longer needed.
• If something from the previous implementation is intentionally retained, explain why.

Handling deviations from the standard

• Treat these rules as strong preferences, not rigid mechanical laws.
• If existing code is outside the standard, report it clearly.
• If the deviation is minor and acceptable, mention it briefly.
• If the deviation is significant and not obviously justified, ask whether to:
  • keep the deviation
  • or refactor toward compliance
• If a deviation is clearly justified by language constraints, framework style, performance needs, safety requirements, or project architecture, keep it and explain it.

Language adaptation

• Adapt these rules to the language and ecosystem instead of applying C/C++ terminology blindly.
• Interpret "function" broadly as the relevant unit of logic: function, method, procedure, hook, handler, endpoint, callback, class method, etc.
• Interpret "structure" broadly as any suitable grouping construct: struct, object, class, record, dataclass, DTO, tuple wrapper, options object, config object, context object, or equivalent.

Expected workflow after code changes

After making changes, when applicable:

1. run relevant tests
2. run lint, format, build, and type-check steps if available
3. report what was verified
4. report what could not be verified
5. summarize remaining risks or uncertainties
6. mention any remaining deviation from these preferences
7. confirm whether old implementation residue remains or has been removed