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.