From 3340b9196bbb1e7f4bb12a9bd4b468579171455b Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:43:13 +0300 Subject: [PATCH 1/7] Add Gemma 4 to the model library --- .config/emacs/site-lisp/local-models.el | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.config/emacs/site-lisp/local-models.el b/.config/emacs/site-lisp/local-models.el index ac695eb..bc9402d 100644 --- a/.config/emacs/site-lisp/local-models.el +++ b/.config/emacs/site-lisp/local-models.el @@ -11,6 +11,14 @@ :context-window 128 :cutoff-date "2024-08" ) + ( + gemma4:latest + :description "A model from Google built on Gemini technology" + :capabilities (media tool-use cache) + :mime-types ("image/bmp" "image/gif" "image/jpeg" "image/png" "image/tiff" "image/webp") + :context-window 128 + :cutoff-date "2025-01" + ) ( hf.co/Orenguteng/Llama-3.1-8B-Lexi-Uncensored-V2-GGUF:latest :description "Uncensored model based on Llama-3.1-8b-Instruct" From bbff7a68d350c48dfa279a7e7687eeb15c79568c Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:51:36 +0300 Subject: [PATCH 2/7] Elaborate on outlier cases in the testing instructions --- .claude/CLAUDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 78f9a62..cbfe821 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -55,6 +55,14 @@ Why this matters: When adding or modifying code, verify that tests cover the new logic. If coverage drops, add tests before merging. +### Coverage Exclusions and Test Quality + +**Pure I/O code is excluded from coverage requirements.** Code whose sole purpose is performing I/O (reading files, making network calls, rendering output) cannot be effectively tested without manual interaction. However, this has a direct design implication: keep the I/O layer as thin and trivial as possible. All business logic, validation, transformation, and decision-making must live in testable modules that the I/O layer merely calls into. A fat I/O layer is a design smell, not an excuse for missing tests. + +**When business logic is tightly coupled to real I/O**, and separating them would genuinely undermine testability (not just convenience), prefer integration tests against an emulated service dedicated for testing. The emulated service must have reliable compatibility with the real target. For example, S3-dependent code can use MinIO via testcontainers or similar tooling to run tests that genuinely need I/O access. This approach is preferable to either mocking away the I/O (which hides real failure modes) or leaving the logic untested. + +**Tests must exercise actual code paths, not reproduce them.** In rare cases, code is so trivial that the only apparent way to test it is to restate it in the test. Such tests verify nothing — they pass by construction and remain passing even when the code changes, which demonstrates that they provide no actual validation. Do not write these. Instead, explicitly exclude the code from coverage. Note that this situation is rare and usually signals a design gap (logic that should be extracted or combined with something more substantive) rather than inherent untestability. + ## CLI Style **Prefer long option names over short ones** in command-line applications and examples. From 7b5628b37b5457fe61fe65a47ede32032f915516 Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:52:23 +0300 Subject: [PATCH 3/7] Clarify the role of integration testing for code that requires I/O --- .claude/CLAUDE.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index cbfe821..ef8f482 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -59,7 +59,11 @@ When adding or modifying code, verify that tests cover the new logic. If coverag **Pure I/O code is excluded from coverage requirements.** Code whose sole purpose is performing I/O (reading files, making network calls, rendering output) cannot be effectively tested without manual interaction. However, this has a direct design implication: keep the I/O layer as thin and trivial as possible. All business logic, validation, transformation, and decision-making must live in testable modules that the I/O layer merely calls into. A fat I/O layer is a design smell, not an excuse for missing tests. -**When business logic is tightly coupled to real I/O**, and separating them would genuinely undermine testability (not just convenience), prefer integration tests against an emulated service dedicated for testing. The emulated service must have reliable compatibility with the real target. For example, S3-dependent code can use MinIO via testcontainers or similar tooling to run tests that genuinely need I/O access. This approach is preferable to either mocking away the I/O (which hides real failure modes) or leaving the logic untested. +**The value of integration testing for I/O is context-dependent** — it depends on whether I/O is incidental to the component or central to its purpose. + +When I/O is incidental (e.g., an application that loads configuration from a file), there is no value in testing the file-reading call itself — trust the language's I/O primitives. Instead, feed raw data to a pure function that handles parsing and validation. In some cases even parsing tests may be unnecessary, such as a JSON config file loaded via a standard-library routine that directly constructs application-defined structs. Structure such code to confine I/O in a short routine that can be excluded from coverage. + +When I/O *is* the core business logic (e.g., a database engine or FUSE filesystem), it must be thoroughly integration-tested against a functioning backend. The I/O layer cannot be excluded here because it is the component's reason for existing. Provision appropriate test infrastructure: a tmpfs filesystem for storage-centric tests, an Alpine testcontainer for cases that need to exercise interactions between different user permissions, or an emulated service with reliable compatibility to the real target (e.g., MinIO via testcontainers for S3-dependent code). This is preferable to either mocking away the I/O (which hides real failure modes) or leaving the logic untested. **Tests must exercise actual code paths, not reproduce them.** In rare cases, code is so trivial that the only apparent way to test it is to restate it in the test. Such tests verify nothing — they pass by construction and remain passing even when the code changes, which demonstrates that they provide no actual validation. Do not write these. Instead, explicitly exclude the code from coverage. Note that this situation is rare and usually signals a design gap (logic that should be extracted or combined with something more substantive) rather than inherent untestability. From a05f054a133aed921060066b5bef026b0fbba2a7 Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:54:03 +0300 Subject: [PATCH 4/7] Describe the preferred setup of green-field projects --- .claude/CLAUDE.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index ef8f482..1368cd6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -80,3 +80,31 @@ command -v -o file.txt ``` Long options are self-documenting and make scripts and examples easier to understand without consulting help text. Short options are acceptable for interactive use but should not appear in committed code, documentation, or examples. + +## Green-Field Project Setup + +When setting up a new project, code-quality and developer-experience tooling must be included from the start and integrated into the development workflow. The principles below use Python as a concrete example, but apply generally to any language ecosystem. + +### Python Tooling + +Use **uv** to manage dependencies and create the project virtual environment. All work must be performed inside the venv. Additionally, install and configure the **pre-commit** hook manager with a baseline DevEx toolset: + +- **ruff** — linting and formatting +- **mypy** — static type checking +- **tach** — structural/dependency boundary checks + +Configure all tools for their strictest check levels by default. Include a `py.typed` marker file in every package to signal PEP 561 compliance. + +### Line Length + +Do not manually break lines to conform to a line-length limit. Automated code formatters (ruff, gofmt, etc.) handle this for source code. Write unbroken lines in text and Markdown files (e.g., README.md) as well. This also applies to one-off files outside of a project context. + +### Licensing (REUSE) + +In all projects, install a **pre-commit hook for the REUSE tool** to lint licensing information and ensure every file has correct SPDX headers. + +Default license assignments: + +- **GPL-3.0-or-later** — source code files in coding projects +- **CC-BY-SA-4.0** — documentation files (README, user guides, etc.); also the default project license for non-coding projects +- **CC0-1.0** — project configuration files (e.g., `pyproject.toml`, `tach.toml`) and small utility scripts or Makefiles that are not core to the implemented logic From 02341ecf9196e65ef07417a60e28f66c9c608dd5 Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:55:06 +0300 Subject: [PATCH 5/7] Invite creative writing in source code --- .claude/CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1368cd6..6d30513 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -40,6 +40,8 @@ Style preferences (when not conflicting with existing patterns): - Avoid mutation of inputs - Pure functions where practical +**Fun is welcome in moderation.** Clarity and readability come first, but the occasional reference, joke, or creative naming makes code more enjoyable to read and write. The key constraint: it must be apropos to the actual code — no random remarks. A comment that winks at a known falsehood the code knowingly embraces, or a function name that doubles as a cultural reference while accurately describing its behavior, are both fair game. Keep it sparse; if every function has a quip, none of them land. + **Style changes should be separate from implementation.** If you notice style inconsistencies or want to improve patterns, do so in dedicated refactor commits or branches rather than mixing with feature work. ## Test Coverage From 5dd645e7fbb8b54f9298249516d3e74ba01a7ff0 Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:55:24 +0300 Subject: [PATCH 6/7] Add guidelines for naming and magic numbers in tests --- .claude/CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 6d30513..c0b06d5 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -42,6 +42,8 @@ Style preferences (when not conflicting with existing patterns): **Fun is welcome in moderation.** Clarity and readability come first, but the occasional reference, joke, or creative naming makes code more enjoyable to read and write. The key constraint: it must be apropos to the actual code — no random remarks. A comment that winks at a known falsehood the code knowingly embraces, or a function name that doubles as a cultural reference while accurately describing its behavior, are both fair game. Keep it sparse; if every function has a quip, none of them land. +**Naming in test code** has different rules than implementation code. Implementation names must always be meaningful and reflective of purpose. Test code, however, may use metasyntactic variables when a value is arbitrary and meaningfulness would be misleading. Preferred metasyntactic names: `foo`, `bar`, `baz`, `frob`, `xyzzy`, and conjugations of `frobnicate`. For arbitrary magic numbers, prefer values with clean ternary representations (e.g., 72 or 243 over 128 or 255 when a test needs a fixed byte value). + **Style changes should be separate from implementation.** If you notice style inconsistencies or want to improve patterns, do so in dedicated refactor commits or branches rather than mixing with feature work. ## Test Coverage From 9423e3ff98d0af29d8fdf3ffa399cf03c89256a6 Mon Sep 17 00:00:00 2001 From: Ohad Livne Date: Sat, 18 Apr 2026 11:55:38 +0300 Subject: [PATCH 7/7] Integrate git into Claude's development process --- .claude/CLAUDE.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c0b06d5..5b26650 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -85,6 +85,12 @@ command -v -o file.txt Long options are self-documenting and make scripts and examples easier to understand without consulting help text. Short options are acceptable for interactive use but should not appear in committed code, documentation, or examples. +## Git Workflow + +Assume you are working in a git repository. Partition changes into small, self-contained commits and commit each before proceeding to the next change. When enacting a plan, a single action item will often span several such commits — that is expected and preferred over bundling unrelated changes together. + +Leverage the git history during development as well. Git enables efficient and reliable rollbacks of recent changes or research dead ends, and clean reverts of specific diffs from earlier in the history. Prefer these over manual cleanup. + ## Green-Field Project Setup When setting up a new project, code-quality and developer-experience tooling must be included from the start and integrated into the development workflow. The principles below use Python as a concrete example, but apply generally to any language ecosystem.