해외 개발자가 소개한 파이썬 표준 패키지 관리 도구 uv 개발팀의 AGENTS.md 속 한 줄이 너무 실용적이다.

【저장 권장】
해외 개발자가 소개한, 파이썬(Python)의 표준 패키지 관리 도구인 uv 개발팀이 AGENTS.md에 넣은 한 줄이 너무나 실용적입니다😳

이를 한국어로 규칙화하자면 다음과 같습니다.

“대화 내용, 프롬프트, 재작업 과정을 코드 주석이나 풀 리퀘스트 설명에 기록하지 말 것.
대화를 보지 않은 사람이 읽는다는 전제하에 작성할 것.”라는 규칙입니다.

이것은 겉보기에는 평범해 보이지만 AI가 생성한 코드의 가독성을 크게 좌우합니다.

AI에게 수정하게 하면, 코드에 다음과 같은 주석들이 남기 쉽습니다.

“# used to be x; now y”
“# changed from v1 as requested”
“// previously this returned null”

하지만 나중에 그 코드를 읽는 사람은 대화 내용을 보지 않은 사람입니다.

게다가 Claude Code를 사용하면, 단순히 규칙으로 요청하는 것뿐만 아니라 PreToolUse 훅(hook)을 사용하여 해당 편집 자체를 막을 수 있습니다.

즉, 단지 '요청'에 그치는 것이 아니라, '쓰면 차단한다'는 메커니즘까지 넣을 수 있게 됩니다.

작성자가 이미지로 공개한 방법은 다음과 같습니다.

• ~/.claude/hooks/no-chat-comments.sh 파일에 셸 스크립트(shell script)를 하나 배치합니다.
• “changed from”, “used to be”, “as requested” 등을 포함하는 주석을 찾습니다.
• 발견되면 exit 2로 편집을 중단하고, “Write comments for the code, not the chat”이라고 반환합니다.
• settings.json의 PreToolUse에 Edit, Write, MultiEdit를 대상으로 등록합니다.
• 새로운 주석을 모두 막는 방법도 같은 스크립트에 작성되어 있습니다.

요컨대, AI에게 코드를 수정하게 하는 시대에서, 수정한 '과정(経緯)' 자체를 코드에 남기지 않는 시대로 진입하고 있다는 것입니다.

Claude Code를 사용하는 사람이라면,
이 한 줄의 스크립트와 훅 하나만으로 주석의 질이 정말 달라집니다.

단순히 “수정해줘”가 아니라, “과정은 코드에 적지 마”까지 AI 코딩을 할 수 있게 된 것입니다.

훅(hook)과 CLAUDE.md를 어떻게 조합하여 사용하는지에 대한 내용은 Anthropic 내부의 방식을 보면 한 번에 정리할 수 있습니다.
Claude Code 운영의 베스트 프랙티스(best practice)를 정리한 글은, 여기서 읽을 수 있습니다.