09.04 — CLAUDE.md and CLAUDE.slim.md#

The Holy Book actively publishes the CLAUDE.md files. This lets an LLM fetch the project’s docs without going through the repo.

The two files#

ai/
├── CLAUDE.md       # full version (rules + project layout)
└── CLAUDE.slim.md  # short version (rules only)

Public URLs#

https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md

Holy Book quote (chapter “Using Ocarina with AI”):

Slim when context is heavy; full for onboarding and reviews. Full wins on disagreement.

Slim/Full differences#

Right file at the right time#

Onboarding (first contact with the project)  →  CLAUDE.md  (read all)
Normal run (just apply rules)                 →  CLAUDE.slim.md (save tokens)
PR review                                     →  CLAUDE.md (justifications)
Deep audit                                    →  CLAUDE.md (everything)

CLAUDE.md#

Typical sections (based on ocarina-with-ai-example):

1. Project context: repo, framework, SUT.
2. Project philosophy: “No tricks or hacks”, “Teach the pattern, not the symptom”.
3. Layout: full repo tree.
4. Conventions: 12+ concrete rules.
5. Hard-won rules: lessons from past failures.
6. Test strategy: cycle structure.
7. Running tests: CLI commands.
8. Reports and screenshots: usage rules.
9. Scenario fragments: extraction criteria.
10. Data-driven tests: conventions.
11. Supplementary conventions.

CLAUDE.slim.md#

Just the rules (no detailed justifications, no examples):

# Slim rules — Ocarina with AI example

- No tricks or hacks. Polling fix > JS click bypass.
- Teach the pattern, not the symptom.
- Security tests: functional and static, never active.
- Use constants: no magic numbers.
- Datasets: human decision; propose, don't execute.
- Empirically verify the SUT before encoding.
- Re-derive each run: no diagnosis inheritance.
- One scenario per file (data-driven exception).
- Top docstring as arrows flow.
- All create_selenium_test() at bottom of file.
- POM selectors at top of class.
- Always WebDriverWait, never raw find_element.
- Implicit wait set by CLI, never patched in POM/test code.
- Gap tests: reframed, not flipped to green.
- Watcher signals: negative only.
- Distributed when resource is shared.
- Mtime, not filename.
- ...

Each line = one rule.

Why expose to LLMs#

The user doc vs LLM doc distinction#

Three audiences, three formats. The Holy Book serves all three — the practical embodiment of “AI is the bridge”.

“Canonical resources” pattern#

URLs are stable:

https://mojo-molotov.github.io/ocarina-holy-book/llms.txt
https://mojo-molotov.github.io/ocarina-holy-book/llms-full.txt
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md
https://mojo-molotov.github.io/ocarina-holy-book/ocarina-ru.pdf
https://mojo-molotov.github.io/ocarina-holy-book/ocarina-en.pdf
https://mojo-molotov.github.io/ocarina-holy-book/ocarina-fr.pdf

Documented in the Holy Book (chapter “Using Ocarina with AI”), at the end:

Exposed resources#

• https://mojo-molotov.github.io/ocarina-holy-book/llms.txt
• https://mojo-molotov.github.io/ocarina-holy-book/llms-full.txt
• https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
• https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md
• https://mojo-molotov.github.io/ocarina-holy-book/ocarina-ru.pdf
• https://mojo-molotov.github.io/ocarina-holy-book/ocarina-en.pdf
• https://mojo-molotov.github.io/ocarina-holy-book/ocarina-fr.pdf