Han Blog에서 정한 코딩 스탠다드를 AI 코드 어시스턴트에 적용하기 위한 공개 배포 저장소다. Claude Code, GitHub Copilot, Codex가 같은 규칙을 사용한다.
설치 스크립트는 최신 vX.Y.Z 태그를 확인하고 시스템 임시 디렉터리에 저장소를 얕게 clone한 뒤,
필요한 파일만 프로젝트 루트에 복사한다. 대상 프로젝트 안에 중첩된 .git은 남지 않는다.
대상 프로젝트 루트에서 실행한다.
$installer = Join-Path $env:TEMP 'coding-standards-update.ps1'
Invoke-WebRequest `
'https://raw.githubusercontent.com/TaegyuHan/coding-standards/main/scripts/update.ps1' `
-OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer -Target $PWD대상 프로젝트 루트에서 실행한다.
installer=$(mktemp)
curl -fsSL \
https://raw.githubusercontent.com/TaegyuHan/coding-standards/main/scripts/update.sh \
-o "$installer"
bash "$installer" "$PWD"
rm -f "$installer"설치 후에는 대상 프로젝트에 저장된 업데이트 스크립트를 언제든 다시 실행할 수 있다.
# Windows: 최신 버전
powershell -NoProfile -ExecutionPolicy Bypass -File .\.coding-standards\update.ps1
# Windows: 특정 버전
powershell -NoProfile -ExecutionPolicy Bypass -File .\.coding-standards\update.ps1 -Version v1.0.0# Ubuntu: 최신 버전
bash .coding-standards/update.sh
# Ubuntu: 특정 버전
bash .coding-standards/update.sh "$PWD" v1.0.0현재 설치 버전은 .coding-standards/manifest.json에 기록된다. 요청한 버전과 같으면 아무것도 복사하지 않는다.
버전이 다르면 기존 관리 경로를 .coding-standards/backups/<시각>/에 백업한 뒤 새 버전을 설치한다.
설치기는
AGENTS.md,CLAUDE.md,.agents,.claude,.codex, Copilot 지침을 관리한다. 대상 프로젝트에 같은 경로의 고유 설정이 있다면 백업 내용을 확인해 필요한 설정을 다시 병합한다.
프로젝트 루트/
├── CLAUDE.md ← Claude 1단. 항상 적용되는 짧은 규칙
├── AGENTS.md ← Codex 1단. 항상 적용되는 짧은 규칙
├── .claude/
│ ├── settings.json ← 2단. 훅 설정 (기본값은 Windows)
│ ├── hooks/
│ │ ├── java-standard-reminder.ps1 ← 2단. Windows / PowerShell
│ │ └── java-standard-reminder.sh ← 2단. macOS / Linux
│ └── skills/ ← 3단. 규칙 본문
├── .agents/
│ └── skills/ ← Codex 3단. Claude와 같은 규칙 본문
├── .codex/
│ ├── hooks.json ← Codex 2단. 종료 전 검토 훅 (기본값은 Windows)
│ └── hooks/
│ ├── java-standard-review.ps1 ← Codex 2단. Windows / PowerShell
│ └── java-standard-review.sh ← Codex 2단. macOS / Linux
└── .github/
├── copilot-instructions.md ← Copilot 1단. 항상 적용
└── instructions/ ← Copilot 2단. applyTo 경로별 자동 적용
이미 CLAUDE.md나 AGENTS.md가 있다면 내용을 이어 붙인다. .claude/settings.json이나
.codex/hooks.json이 있다면 hooks 항목만 병합한다.
settings.json의 기본값은 Windows(PowerShell)다. macOS·Linux라면 command를 아래로 바꾼다.
"command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/java-standard-reminder.sh\""두 스크립트는 같은 매핑(계층 → 표준) 을 갖는다. 계층을 바꾸면 둘을 함께 고친다.
SKILL.md와 instructions.md를 함께 움직이는 것과 같은 이유다.
Codex 훅도 기본값은 Windows(PowerShell)다. macOS·Linux라면 .codex/hooks.json의 command를
아래로 바꾼다.
"command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/java-standard-review.sh\""Codex는 프로젝트 훅을 처음 실행할 때 신뢰 확인을 요구한다. Codex CLI의 /hooks에서 내용을 검토하고
신뢰해야 실제로 동작한다.
전부 CLAUDE.md에 넣으면 확실히 적용되지만 매 요청에 25~30k 토큰을 낸다.
전부 스킬에 넣으면 싸지만 모델이 부를지 판단해야 해서 한 번 놓치면 그 코드는 표준을 벗어난다.
그래서 빈도 × 길이로 나눴다.
| 무엇을 담나 | 언제 들어오나 | 비용 | |
|---|---|---|---|
1단 CLAUDE.md / AGENTS.md |
말 안 하면 기본값으로 어기는 짧은 규칙 | 코드를 만들기 전 | 약 600토큰, 캐시됨 |
| 2단 훅 | 경로별로 어느 스킬을 볼지만 | 자바 파일 저장 직전 | 평소 0, 발동 시 한 줄 |
| 3단 스킬 | 규칙 본문·근거·예외 | 필요할 때 | 그때만 |
1단은 예방이고 2단은 검문이다. CLAUDE.md는 생성 전에 있으므로 코드 자체를 바꾸고,
훅은 이미 만들어진 호출 직전에 돌아 놓친 것을 잡는다.
세 단이 겹치지 않는다. 1단은 규칙을 갖고, 2단은 신호만 주고, 3단은 본문을 갖는다. 훅에 규칙 내용을 넣으면 1단과 중복되면서 파일을 만질 때마다 토큰이 쌓이므로 넣지 않는다.
스킬의 이름과 설명은 Claude Code가 자동으로 보여주므로 CLAUDE.md에 목록을 다시 적지 않는다.
Codex는 저장소의 AGENTS.md를 자동으로 읽고 .agents/skills/의 스킬 이름과 설명을 먼저 본다.
작업이 스킬 설명과 일치하면 전체 SKILL.md를 읽는다. Claude와 같은 상세 규칙을 쓰기 위해
.claude/skills/와 .agents/skills/는 같은 디렉터리 이름과 같은 SKILL.md 본문을 유지한다.
Codex 훅은 Claude 훅과 입력 형식이 달라 스크립트를 공유하지 않는다. Claude 훅은 Java 파일을 쓰기 직전에
경로별 표준을 알리고, Codex Stop 훅은 변경된 Java 파일이 있으면 종료 직전에 관련 스킬을 읽고 대조한 뒤
테스트하도록 한 번 더 작업을 이어간다. 두 훅의 시점은 다르지만 역할은 같은 2단 검문이다.
Claude에 훅을 둔 이유는 경로 기반 자동 주입이 없어서였다. Copilot에는 applyTo 글롭이 이미 있고,
포인터가 아니라 규칙 본문 자체를 실어준다. 그래서 훅에 해당하는 단이 필요 없다.
| 1단 | 2단 | |
|---|---|---|
| Claude | CLAUDE.md |
훅(포인터) + 스킬(본문) |
| Codex | AGENTS.md |
Stop 훅(검문) + .agents/skills(본문) |
| Copilot | .github/copilot-instructions.md |
instructions/*.md (applyTo가 본문까지 실어준다) |
applyTo는 표준마다 실제로 걸리는 계층으로 좁힌다. 전부 **/*.java로 두면 자바 파일 하나를 열 때마다
16개가 통째로 들어온다. Controller를 짜는데 SkipPolicy와 orphanRemoval 규칙이 섞이면
모델이 엉뚱한 것을 적용할 여지가 생긴다.
패키지 구조·DTO 네이밍·DTO 생성·예외 코드·검증은 원래 전 계층에 걸리므로 **/*.java로 둔다.
억지로 쪼개면 규칙이 조각나서 관리가 무너진다.
CLAUDE.md, AGENTS.md, .github/copilot-instructions.md는 같은 12줄이다. 하나를 고치면 셋을 함께 고친다.
Claude와 Codex의 SKILL.md, Copilot의 instructions.md도 함께 움직인다.
-
.ps1파일은 반드시 UTF-8 BOM으로 저장한다. PowerShell 5.1은 BOM이 없으면 ANSI로 읽어 한글이 깨지고, 깨진 문자열이 파서 오류로 번져 훅이 통째로 죽는다. 편집기에서 인코딩을 바꿨다면 아래로 확인한다.[System.IO.File]::ReadAllBytes("$PWD\.claude\hooks\java-standard-reminder.ps1")[0..2] # 239 187 191 (EF BB BF) 이어야 한다
-
bash 쪽은
jq가 있으면 쓰고 없으면sed로 대체하므로 별도 설치가 필요 없다 -
훅이 실제로 발동하는지 자바 파일을 하나 만들어 확인한다. 스크립트 단독 실행이 되는 것과 Claude Code가 훅을 부르는 것은 별개다
-
1단 목록은 고정이 아니다. 써보면서 계속 어기는 규칙은 올리고, 한 번도 안 어기는 규칙은 내린다
-
Codex 스킬 동등성을 확인한다.
.claude/skills와.agents/skills의 디렉터리 목록과 각SKILL.md바이트가 모두 같아야 한다 -
Codex 훅을 신뢰하고 실제로 발동하는지 확인한다. Java 파일을 수정한 뒤 종료할 때 관련 스킬 검토와 테스트 요청으로 한 번 이어져야 한다
-
설치나 업데이트 뒤
.coding-standards/manifest.json의 버전을 확인한다 -
기존 설정이 있던 프로젝트라면
.coding-standards/backups/에서 병합할 내용을 확인한다
전체 목록과 각 표준을 정한 이유는 코딩 스탠다드 인덱스에 있다. 아직 정하지 않은 것은 열린 항목에 모아둔다.