AGENTS.md에 린팅 규칙을 나열하는 방식은 LLM이 잊거나 무시할 수 있다. Evil Martians가 제안하는 더 나은 패턴: Claude Code의 Stop hook에 nano-staged를 연결해 규칙을 강제 실행 코드로 만든다.

“툴로 인코딩할 수 있는 규칙은 LLM이 잊을 수 없다. AGENTS.md에 규칙을 적는 팀과 자동화로 지키는 팀의 차이는 앞으로 크게 벌어질 것이다.”

핵심 원칙

• 문서 → 자동화: 규칙을 글로 쓰지 말고, 에이전트가 멈출 때마다 실행되는 명령으로 만들어라
• 토큰 절약: 매번 린팅 규칙을 프롬프트에 포함하는 대신 hook으로 처리하면 토큰을 아낀다
• 일관성 보장: 사람과 에이전트 모두 동일한 코드 품질 게이트를 통과한다

설정 방법 (4단계)

1단계: nano-staged 설치

pnpm add --save-dev nano-staged

2단계: .nano-staged.json 설정

파일 타입별로 적합한 린터를 지정한다:

{
  "*": "oxfmt --no-error-on-unmatched-pattern",
  "**/*.{js,ts,jsx,tsx}": "oxlint",
  "**/*.css": "stylelint --fix"
}

3단계: Claude Code Stop hook 추가

.claude/settings.json에 Stop hook을 추가한다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./node_modules/.bin/nano-staged --unstaged --quiet --bail || exit 2"
          }
        ]
      }
    ]
  }
}

--bail은 첫 번째 실패 시 즉시 종료하고, exit 2는 에이전트에게 오류를 알린다. 에이전트는 오류를 받아 스스로 수정을 시도한다.

4단계: (권장) husky로 git commit에도 연결

사람의 커밋에도 동일한 린팅을 적용한다:

pnpm add --save-dev husky
pnpm husky init
echo "./node_modules/.bin/nano-staged" > .husky/pre-commit

결과

• Claude Code가 파일을 수정하고 멈출 때마다 자동으로 lint가 실행된다
• 린팅 실패 시 에이전트는 오류를 받아 스스로 수정한다
• AGENTS.md에서 린팅 관련 줄을 삭제해도 된다

비JS 프로젝트

JavaScript 외 프로젝트에는 nano-staged 대신 Lefthook을 사용한다. 동일한 원칙(hook에 린터 연결)을 언어 무관하게 적용할 수 있다.

참고 자료

• Stop writing rules in AGENTS.md: use agent hooks and nano-staged instead — Evil Martians (2026-05-27)