# Claude Code rules

- **Root directory**: In the following, $THISLIB stands for the root of
  the library source directory. It is the directory where this Claude session
  was launched. It contains this CLAUDE.md.

### Bash commands for use in directory $THISLIB/build/:
- run CMake as follows: cmake .. -GNinja
  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DDEV=ON
- If source files have been renamed or removed, we may need to remove CMake
  caches. Use `cd $THISLIB/build && rm -rf CM*`.
- Never run `rm -rf *`. If you really need full cleanup, ask the user to do it.
- run tests with moderate number of processors, as most code under test is
  internally parallized: ctest -j8
- re-run failed tests: ctest --rerun-failed --output-on-failure

### Bash commands for use in directory $THISLIB/debug/:
- run CMake: cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug
  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
- run gdb not on ctest, but on single test binaries from build/
  subdirectory bin/

### Build system and compilation
- For building and testing, always work from $THISLIB/build.
- To compile, run ninja (pre-approved).
- If compilation fails, address errors before proceeding.
- Before declaring success and proposing a commit, always run ctest -j8
  (pre-approved).
- To investigate failed tests, only run the failed tests, or inspect
  Testing/Temporary/LastTest.log.

### File formatting
- Follow existing code conventions and patterns in the codebase.
- When you create new files, use the current year in the copyright line in
  the standard header comment.
- Format of C++ source files (.h, .cpp) is defined by $BA/.clang-format.
  Before proposing a commit, if in doubt, reformat modified C++ source
  files using "clang-format -i".
- Format of Python sources (.py) is defined by $BA/.style.yapf.
- No double blank lines inside blocks, functions, classes. And rarely ever
  between function definitions.
- In CMake sources (CMakeLists.txt and .cmake), maximum 100 chars/row.
- In text files (including .md), maximum 80 chars/row. When
  reformatting, unless told differently, correct only paragraphs that
  have overfull lines. Underfull lines may be due to semantically
  meaningful line breaking and must therefore not be touched.
- In new LaTeX sources (.tex), we aim for maximum 80 chars/row. In extant
  sources, we tolerate up to 100 chars/row.

### C++ coding rules
- In general, follow the coding style of extant code.
- However, always obey the following rules, and complain if they are
  violated in the neighborhood of code you have to change.
- Source formatting:
  - Rules in $BA/.clang-format are absolutely binding, enforced by clang-format -i.
  - No braces around single statements, except possibly to keep if and else
    clauses analogous.
  - Double blank line between namespace blocks and class implementation.
- Include order:
  - In A.cpp, header A.h is included first.
  - Then all other in-project headers in alphabetic order, in "...".
  - Then the <...> includes in alphabetic order.
  - This is enforced anyway by clang-format.
- Naming conventions:
  - Function names are in camelCase (e.g., readData2D, writeDatafield).
  - Variable names are in snake_case (e.g., input_stream, file_name).
  - Class names are in PascalCase (e.g., Datafield, ImportSettings2D).
  - Member variables use m_ prefix (e.g., m_model_data).
  - Constants use uppercase with underscores (e.g., MAX_SIZE).
- When a function from a local (anonymous) namespace is called from outside
  that namespace, then use prefix "::" in the function call.
- Error handling:
  - Throw an exception to react to invalid input.
  - Call ASSERT_NEVER, or use a simple ASSERT for the entire check,
    to react to cases that can only arise as consequence of a bug.
- API design:
  - Mirror conventions between similar classes or functions (e.g., 1D and 2D I/O).

## Interacting with Git and Gitlab

### Git stage and commit
- Propose a commit if and only if
  - a task, or a major subtask, is done,
  - all modified files are correctly formatted (see above, File Formatting),
  - compilation has succeeded, and
  - ctest has passed.
- If compilation has changed files under auto/, then these need to be added
  to the commit.
- Before committing a bug resolution, changes of the API, or the endpoint of
  a major refactoring thread, propose adding a line to the CHANGELOG.
- Do git add and git commit in one go, but only after I gave permission.
- Use `git commit --amend` only for corrections and trivial cleanup. Incremental
  improvements go into separate commits.

### Commit messages
- Always start commit messages with "[claude] ".
- Use clear, descriptive commit messages that explain the "why" not just
  the "what".
- End commit messages without any footer. No need for the standard Claude
  attribution (🤖 Generated ...).
- If a commit contributes to resolving a given issue, say #1234, then the
  header of the commit message shall terminate with " (#1234)".
- If a commit fully resolves the issue, then in addition to the above
  append a paragraph at the end of the commit message to say "This resolves
  #1234."

### Root forge at Jugit
- The forge for this library is at https://jugit.fz-juelich.de/mlz/libformfactor/.
- Jugit is our corporate Gitlab instance.
- You may access Jugit through glab.
- You have unlimited read access.
- You may write to the library forge when explicitly instructed or when
  given permission.
- When you create issues or merge requests, start title with "[claude] ".
- Also, when editing issue descriptions or adding comments, always make
  clear what is Claude-generated text.

### Merge request (MR)
- When submitting MR include a detailed message. Before writing this message,
  reread the git history: The message shall cover all changes since bifurcating
  from origin/develop.
- Always start MR messages with "[claude] ".
- If a MR contributes to resolving a given issue, say #1234, then the
  header of the commit message shall terminate with " (#1234)".
- If a MR fully resolves the issue, then in addition to the above append
  a paragraph at the end of the commit message to say "This resolves #1234."
- Ensure the flag "Delete source branch when merge request is accepted"
  is set to true.
