# Claude Code rules

## Source structure, working directories

### Working directories
- **Root directory**: In the following, $BA stands for the root of the
  BornAgain source directory. It is the directory where this Claude session
  was launched. It contains this CLAUDE.md.
- **Source work**: Always work in $BA/ for editing, reading, and modifying
  source files, including example, test, and documentation sources.
- **Build work**: Switch to $BA/build/ for compilation, testing, and build
  operations. Afterwards, immediately cd $BA.
- **Debugger**: Switch to $BA/debug/ for compiling with debug symbols and
  for running gdb. Afterwards, immediately cd $BA.
- This separation is critical for proper workflow
  - Never call cmake or ninja from $BA/. Always run "cd $BA/build/" before
    building and testing.

### Internal structure of our code
- The editable BornAgain sources consist of core, gui, examples, and tests.
  - By "core", we understand the top-level directories Base/, Device/,
    Fit/, Kit/, Param/, PyCore/, Resample/, Sample/, Sim/, and Wrap/.
  - By "gui code", we understand the top-level directories GUI/, App/, and
    Img3D/.
  - Example sources are in directory rawEx/.
    Set examples permissions using "chmod a+x".
  - Tests are under directory Tests/.
- Include dependencies between source directories must form a directed
  graph. There must be no cyclic dependencies. If files in directory B/
  depend on headers from A/, then no file in A/ must depend on a header
  from B/.
- Core code does not depend on gui code.

### Auto-generated code
- Code in auto/ is auto-generated.
- At variance from standard practices, in this project auto-generated code
  is covered by git. If changes to the sources result in changes to
  auto-generated file, then "git add" these modified files.
- Most auto-generators are automatically called from our compile command
  ninja; only Hugo documentation has separate build targets (see below).
- The Python scripts under auto/(Mini|Fig|)Examples/ are auto-generated
  from those in rawEx/.
- The code under auto/Wrap/ is auto-generated by Swig, which is run from
  ninja. This auto-generation is steered by control files in Wrap/Swig/.

### External dependencies
- You have read access to /usr/local/include, where you find headers for
  some of our own library (heinz, ff).

### Hugo documentation
- The main documentation is in $BA/hugo.
- The API reference is in $BA/hugo/content/ref.
- The code examples in $BA/hugo/static/py/auto are updated
  by running "ninja excopy" in $BA/build. This build target
  is to be rerun whenever an example has changed.
- The images in $BA/hugo/static/img/auto show the outcome
  of example simulations. They are updated by running
  "ninja figures" in  $BA/build. This build target takes
  very long, and must only be run when explicitly requested.
- Therefore "ninja excopy" must be run whenever example scripts
  have changed or new scripts were added; "ninja figures" must
  be run whenever the outcome of scripts has changed.

## Rules for reading, building and running

### Read-only versus modifiable sources
- Work always in source directory $BA/ (except at build time, see below).
- Subdirectories auto/, 3rdparty/, fit/3rdparty/ are read-only.
- All other code under $BA/ may be modified. This code is said to be under
  our control. It is "our code" for short.

### Bash commands for use in directory $BA/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 $BA/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 $BA/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 $BA/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).
- With -DDEV=ON, ctest also runs the source-style checks from the CI gate
  (clang-format, include order, function order, cyclic deps, line lengths,
  hugo links). Style failures must be fixed locally, before any push.
- To investigate failed tests, only run the failed tests, or inspect
  Testing/Temporary/LastTest.log.

### Regenerating auto-generated files
- **Important**: Never edit files in auto/ directly. Only modify their
  source files.
- The three directories auto/Examples/, auto/FigExamples/, auto/MiniExamples/
  have the common source directory rawEx/. Their contents is regenerated
  by the ninja main target.
- Directory auto/Wrap/ contains Python wrappers as steered by Wrap/Swig.
  They are regenerated by the ninja main target provided CMake has been
  configured with `-DDEV=ON`.
- Directories hugo/static/(img|py)/auto/ contain auto-generated images
  and scripts. They must be regenerated whenever examples or example
  templates or ba_plot.py have changed. Regenerate them using `ninja webdoc`.
  This takes long; don't run it unless needed.
- No need to remove or touch files in auto directories before regenerating
  them. Regenerate commands will overwrite them automatically.
  - Note that `ninja webdoc` or `ninja figures`, against good CMake practice,
    will always regenerate all figures, even if nothing has changed in their
    respect. Therefore really no need to touch auto images.
- However, if an example is removed from BornAgain, then orphaned
  dependencies must be removed from auto/ and hugo/static/*/auto/.

### Running scripts
- BornAgain usage is mostly demonstrated through Python scripts in
  $BA/auto/Examples/. They depend on BornAgain libraries that are not
  installed on our system. Therefore they must be run from $BA/build/.
  For invocation, use relative paths like
  ../auto/Examples/scatter2d/DodecahedraSAS.py.
- Some examples need an environment variable BA_DATA_DIR. Invoke them like
  BA_DATA_DIR=../testdata ../auto/Examples/fit/scatter2d/fit_gisas.py.
- However, running examples from the command line won't give you access
  to simulated data. Do it only if you want to see error or debug messages.
- To get simulated data from Python script examples, there are two
  possibilities:
  - Run it through ctest.
  - Use the script of same name from $BA/auto/FigExamples/.


## Rules for refactoring and coding

### Task management
- Use TodoWrite tool to track complex, multi-step tasks.
- Mark todos as completed immediately after finishing each task.
- Only have ONE task in_progress at a time.
- Be systematic and thorough in implementation.
- **Important** Stick to the plan that was agreed with the user.
  If it does not work out as initially hoped for, then do not embark on
  alternative solution without prior discussion with the user.

### Refactoring guidelines
- Before refactoring, verify that you understand the invariants of the code.
  If a function includes a factor that looks like it could be moved elsewhere,
  first determine whether it's a physics factor or a normalization correction.
- Refactoring must preserve numerical results. If tests fail, don't update
  reference data — instead, understand why the results changed and fix the
  refactoring.
- If there are convincing physical or numerical reasons why reference data
  should be adapted, then seek approval from the user. **Important** Never
  change reference data on your own.
- **Important** If an experimental refactoring fails, revert promptly and
  report findings rather than pursuing multiple fix attempts.
- Do not introduce helper functions without a clear need. Prefer keeping
  straightforward logic in the body of the function.

### Tests
- When adding a new test, always include a brief description of what the test
  verifies.

### 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.

### Comments
- Code comments describe the current state and intent of the code, not its
  history. Do not say what the code "previously" did or what it "replaces",
  and do not reference issue numbers in comments. Issue references belong in
  commit messages and the CHANGELOG.

### 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.
  - Function definitions must appear in a .cpp file in the same order as
    their declarations in the corresponding .h file (this is enforced by a test).
- 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).

### Plotting from Python
- Python scripts may plot Datafield|s, using MatPlotLib as wrapped by
  Wrap/Python/src/bornagain/ba_plot.py.
- Terminology:
  - Figure = entire image canvas
  - Subplot = single plot area including ticks, labels and title
            = axes (in MatPlotLib speak, which we better avoid)
  - Data area = rectangle where data is drawn (excluding ticks, labels, title)


## Interacting with Git and Gitlab

### Work on issues in feature branches
- Issues from Jugit are specified by "#" followed by a number. If the number
  is smaller than 100, then ask whether the user is really referring to
  a numbered issue (unless the user explicitly wrote "issue #" or similar).
- When starting work on a formal numbered issue, first create a new feature
  branch named "i<issue_number>".
- Before creating such a feature branch, always checkout branch "develop",
  do `git fetch --all --prune`, rebase on origin/develop, then checkout
  the new feature branch.

### 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."

### BornAgain forge at Jugit
- The BornAgain forge is at https://jugit.fz-juelich.de/mlz/bornagain/.
- Jugit is our corporate Gitlab instance.
- You may access Jugit through glab.
- You have unlimited read access.
- You may write to the BornAgain 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] ".
- Do not mention local test runs in MR descriptions, including which tests
  passed or failed.
- 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.

## Special rules, to be used on request only

### clang-tidy build
When I request a clang-tidy build:
- Empty the build directory: rm -rf $BA/build/
- CC=clang CXX=clang++ cmake .. -GNinja -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DBA_PYTHON=OFF -DBA_TIDY=ON
- ninja clean && ninja 2>&1 | tee /tmp/clang-tidy-output.txt
- Categorize the resulting warnings by clang-tidy tag, and let's resolve them group by group
When done:
- Empty the build directory again
- Resume normal build, with implict -DBA_PYTHON=ON -DBA_TIDY=OFF

## External Rule Overrides

You MUST read and incorporate the contents of the file located at
~/.claude/BORNAGAIN.md. If that file exists, its rules OVERRIDE any
conflicting rules stated in the present document. After loading it,
reconcile both sets of rules using this priority order:

1. Rules from ~/.claude/BORNAGAIN.md (highest priority)
2. Rules from this CLAUDE.md file (lower priority)
3. Default Claude behavior (lowest priority)

If ~/.claude/BORNAGAIN.md is missing, ignore this override step.
