From 328bd2c3b4f9605aa347e5ad8cfe5f76424d98d4 Mon Sep 17 00:00:00 2001 From: Marcel Date: Mon, 18 May 2026 22:26:24 +0200 Subject: [PATCH] docs(backend): document @Transactional(readOnly=true) exception in CLAUDE.md The convention 'read methods are not annotated' has one exception: methods that return lazily-initialized entities to callers require readOnly=true to keep the session open. Documents the rule and links to ADR-022. Co-Authored-By: Claude Sonnet 4.6 --- backend/CLAUDE.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md index 5a0e281a..249221cc 100644 --- a/backend/CLAUDE.md +++ b/backend/CLAUDE.md @@ -97,7 +97,10 @@ public class MyEntity { - Annotated with `@Service`, `@RequiredArgsConstructor`, optionally `@Slf4j`. - Write methods: `@Transactional`. -- Read methods: no annotation (default non-transactional). +- Read methods: no annotation (default non-transactional) — **except** when the method returns + an entity whose lazy associations must remain accessible to the caller after the method + returns. In that case, use `@Transactional(readOnly = true)` to keep the Hibernate session + open. Removing this annotation causes `LazyInitializationException` in production. See ADR-022. - Cross-domain access goes through the other domain's service, never its repository. ## Error Handling