exception-logging — правило для Claude Code: как установить
Правило exception-logging для Claude Code проверяет обработку исключений и логирование в коде на Java. Контролирует пустые блоки catch, вызовы SLF4J, маскирование данных и откат транзакций.
MIT ★ 517 обновлён 2026-11-16
.claude/rules/exception-logging.mdЧто делает exception-logging
Правило задаёт семантические требования к обработке исключений и оформлению логов в Java-проектах. Оно запрещает пустые блоки catch, инструкции return внутри секций finally и перехват NullPointerException вместо явных проверок на null. Для цепочек вызовов вложенных объектов правило требует использовать Optional, а при работе с потоками ввода-вывода — синтаксис try-with-resources.
В методах с аннотацией @Transactional при перехвате ошибок правило обязывает явно вызывать TransactionAspectSupport.currentTransactionStatus().setRollbackOnly(). Логирование переводится на фасад SLF4J вместо прямого импорта классов Log4j или Logback. Вместо склейки строк правило требует использовать плейсхолдеры {}, а персональные данные вроде номеров телефонов и паспортов маскировать через вспомогательные утилиты. Для предотвращения дублирования записей в logback.xml проверяется атрибут additivity="false".
Без настроенного фасада SLF4J и функций маскирования агент будет помечать прямые вызовы логеров как ошибки.
Какие задачи решает
- находить и устранять пустые блоки catch
- настраивать ручной откат транзакций в блоке catch
- заменять прямые импорты Log4j на фасад SLF4J
- маскировать персональные данные в строках логов
- предотвращать возврат значений из блока finally
Примеры запросов агенту
- Проверь сервис
UserService.javaпо правилам exception-logging - Исправь логирование ошибок и добавь плейсхолдеры в методе
updateUser - Перепиши каскадные вызовы через
Optionalи закрой ресурсы в try-with-resources
Как установить exception-logging
Вручную: положить файлы
.claude/rules/exception-logging.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/exception-logging.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/exception-logging.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/exception-logging.mdВручную: положить файлы
.clinerules/exception-logging.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы об exception-logging
Как установить exception-logging в Claude Code?
Сохраните файл правила по пути .claude/rules/exception-logging.md в корне репозитория.
Какие требования правило предъявляет к логированию?
Оно предписывает работать через интерфейс SLF4J, использовать подстановку аргументов через {} вместо конкатенации строк, передавать объект исключения для сохранения стека и скрывать чувствительные данные.
Что требует правило при обработке ошибок в транзакциях?
Если блок try-catch находится внутри метода @Transactional, в блоке catch необходимо вызвать TransactionAspectSupport.currentTransactionStatus().setRollbackOnly() перед генерацией нового исключения.
Исходный текст
exception-logging.md · MIT
# Exception handling and logging guidelines
## Exception handling
### Exception catching
**Detection mode**: semantic
**Empty catch blocks are forbidden (MULT-EXC-001):**
```java
// Wrong: swallows the exception
try {
doSomething();
} catch (Exception e) {
// empty block
}
// Correct: at least log it
try {
doSomething();
} catch (Exception e) {
log.error("Failed to do something", e);
throw new BusinessException("operation failed", e);
}
```
### Transaction rollback
**Detection mode**: semantic
**Catching an exception in transactional code requires a manual rollback (MULT-EXC-002):**
```java
@Transactional(rollbackFor = Exception.class)
public void updateUser(User user) {
try {
userDao.update(user);
userPhoneDao.update(user.getPhone());
} catch (Exception e) {
log.error("failed to update user", e);
TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
throw new BusinessException("update failed");
}
}
```
### finally rules
**Detection mode**: semantic
**Do not return from finally (MULT-EXC-003):**
```java
// Wrong
try {
return 1;
} finally {
return 2; // Forbidden! Overrides the return in try
}
// Correct
try {
return 1;
} finally {
// Cleanup is allowed here, but no return
}
```
### Resource cleanup
**Detection mode**: semantic
**The finally block must close resources; on JDK 7+ use try-with-resources (MULT-EXC-004):**
```java
// Correct
try (InputStream is = new FileInputStream(file);
OutputStream os = new FileOutputStream(output)) {
// use the resource
} catch (IOException e) {
log.error("IO error", e);
}
```
### Pre-check principle
**Detection mode**: semantic
**Pre-checks are better than exception catching (MULT-EXC-005):**
```java
// Wrong
try {
return user.getName().toUpperCase();
} catch (NullPointerException e) {
return null;
}
// Correct
if (user != null && user.getName() != null) {
return user.getName().toUpperCase();
}
return null;
```
### Exception classification
**Detection mode**: semantic
**Distinguish stable code from unstable code (MULT-EXC-007):**
```java
// Stable code: catch a specific exception
try {
userDao.insert(user);
} catch (DuplicateKeyException e) {
log.warn("Duplicate user: {}", user.getId());
throw new BusinessException("user already exists");
}
// Unstable code: catch a broader exception
try {
thirdPartyService.call();
} catch (Exception e) {
log.error("Third party call failed", e);
throw new ServiceException("third-party service call failed", e);
}
```
### Cascading-call NPEs
**Detection mode**: semantic
**Cascading calls are prone to NPEs; use Optional (MULT-EXC-008):**
```java
// Wrong
String cityName = user.getAddress().getCity().getName();
// Correct
String cityName = Optional.ofNullable(user)
.map(User::getAddress)
.map(Address::getCity)
.map(City::getName)
.orElse("unknown");
```
## Logging
### Logging framework
**Detection mode**: semantic
**Depend on the SLF4J facade; do not use Log4j/Logback APIs directly (MULT-LOG-140):**
```java
// Wrong: use Log4j/Logback directly
import org.apache.log4j.Logger;
// Correct: use SLF4J
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger log = LoggerFactory.getLogger(UserService.class);
```
### Log content
**Detection mode**: semantic
**Exception logs must include context and the stack trace (MULT-LOG-141):**
```java
// Correct
log.error("params: {}, error: {}", userId, e.getMessage(), e);
// Or use placeholders
log.error("failed to update user, userId={}, error={}", userId, e.getMessage(), e);
```
### Conditional output
**Detection mode**: semantic
**Use conditional output or placeholders for trace/debug/info (MULT-LOG-142):**
```java
// Wrong: string concatenation
log.debug("Processing user: " + userId);
// Correct: placeholder
log.debug("Processing user: {}", userId);
// Or conditional output
if (log.isDebugEnabled()) {
log.debug("Processing user: {}", userId);
}
```
### Sensitive-data masking
**Detection mode**: semantic
**Logs must be masked (MULT-SEC-025/026):**
```java
// Wrong: log sensitive information directly
log.info("User login: phone={}, idCard={}", phone, idCard);
// Correct: mask it
log.info("User login: phone={}, idCard={}",
SensitiveDataMasker.maskPhone(phone),
SensitiveDataMasker.maskIdCard(idCard));
// Or use the masking helper
log.info("User login: {}", SensitiveDataMasker.maskUserInfo(user));
```
### Log levels
**Detection mode**: semantic
**Disable debug in production; enable info selectively (MULT-LOG-146):**
```java
// Wrong
log.debug("Detailed info");
// Correct
log.info("Operation info");
log.warn("Warning info");
log.error("Error info", e);
```
### Duplicate logs
**Detection mode**: semantic
**Avoid duplicate log output; set additivity=false (MULT-LOG-143):**
```xml
<!-- logback.xml -->
<logger name="com.example.service" level="INFO" additivity="false">
<appender-ref ref="FILE"/>
</logger>
```
© kyy-logs · MIT · kyy-logs/code-review-gate-skill