Rules 이해
Rule은 Claude가 모든 응답에서 자동으로 따르는 제약입니다.
한 번 설치하면 "always-on" — 매번 설명하지 않아도 됩니다.
한 번 설치하면 "always-on" — 매번 설명하지 않아도 됩니다.
Rule 해부
모든 rule은 YAML frontmatter + 마크다운 본문으로 구성된 단순한 `.md` 파일입니다.
---
name: Plan before code
description: Write and self-review a short
implementation plan before writing or
changing code.
tags: [workflow, planning]
paths:
- "**/*.ts"
- "**/*.tsx"
---
# Plan before code
Before writing or changing any code, write
a short implementation plan:
- Component tree or function signatures
- State and data flow
- Files to touch
Self-review the plan once before starting.
Only after approval, start coding.
name
사람이 읽을 수 있는 이름. TUI와 CLAUDE.md managed block에 표시됩니다.
description
언제 이 rule이 적용되는지 한 문장으로. Claude가 rule의 적용 범위를 판단할 때 사용합니다.
tags
TUI 검색/필터에 사용. FE/BE 공통 여부 구분에도 활용됩니다.
paths (선택)
이 rule이 적용될 파일 glob 패턴. 생략하면 모든 파일에 적용됩니다.
ℹ️ Rule 본문은 Claude의 system context에 직접 주입됩니다. Claude는 이를 절대적 제약으로 취급하고 모든 응답에서 따릅니다. 짧고 명확할수록 효과적입니다.
카테고리 구조
Rule은 rules/<카테고리>/<id>.md 경로에 저장됩니다. 카테고리 폴더 자체가 TUI의 탐색 단위입니다.
workflow
plan-first, fe-tdd, be-tdd, cleanup-after-green
tech-stack
fe-stack-and-commands, be-stack-and-commands
architecture
feature-boundaries
flask-architecture
flask-app-architecture, openapi-first-contract, api-error-and-health
nextjs-boundaries
serializable-boundary-props, hydration-mismatches
type-modeling
no-any, domain-types, python-type-hints
ui-styling-a11y
design-tokens, accessibility
state-error-handling
state-ownership, route-boundaries
naming-conventions
casing, python-casing
security
no-hardcoded-secrets, sanitize-untrusted-input, mask-pii, backend-api-access-control
critic-loop
autonomous-retry
guardrails
protected-config-files, no-reading-generated-trees, protected-config-be
persistence
dynamodb-data-access
exploration
codegraph-first
code-quality
no-comments
dependencies
reuse-before-install
version-control
commits, language-policy
핵심 Rule 5가지 심층 분석
1
Plan before code
workflow/plan-first
코드를 작성하기 전에 항상 짧은 구현 계획을 먼저 작성합니다. 계획에 포함할 내용:
- 컴포넌트 트리 또는 함수 시그니처
- 상태와 데이터 흐름
- 변경할 파일 목록
작성 후 자체 검토 한 번, 승인 후 코딩 시작.
✅ 이유: "생각 없이 코드부터 치는" 패턴을 방지합니다. 계획 단계에서 방향이 잘못됐음을 발견하는 게 코드를 다 짠 후 발견하는 것보다 훨씬 저렴합니다.
2
No
any
type-modeling/no-any
TypeScript any 타입을 금지합니다. 대신:
unknown을 사용하고 타입 가드로 좁히기- 불안전한
as캐스트 피하기 - 외부 API 응답 → Zod/Pydantic으로 검증 후 타입 확정
✅ 이유:
any는 런타임 에러를 타입 시스템에서 숨깁니다. 프로덕션에서 터지는 TypeError의 대부분은 any에서 시작됩니다.
3
No hardcoded secrets
security/no-hardcoded-secrets
비밀을 소스 코드에 커밋하지 않습니다. git에 올라간 비밀은 삭제해도 영원히 히스토리에 남습니다. 대상:
- API 키, 토큰, JWT, private key 블록
- URL에 포함된 자격증명
- 사내 내부 호스트명
stage 전 pre-stage-secret-scan 스킬이 자동 스캔합니다. `.env` 형식 파일뿐 아니라 계획 문서, 스크래치 노트, 픽스처 파일에도 적용됩니다.
✅ 이유: 일반적인 "`.env` 파일만 안 올리면 된다"는 인식이 틀렸습니다. Markdown, JSON fixture, PR description에 붙여넣은 토큰도 동일하게 위험합니다.
4
Autonomous fix loop (max 3)
critic-loop/autonomous-retry
빌드/lint/테스트 실패 시 자율적으로 수정을 시도합니다. 규칙:
- 최대 3회까지 자율 수정 시도
- 각 시도 전에 실패 로그를 분석하고 근본 원인 파악
- 3회 후에도 실패 → 사람에게 에스컬레이션 (상황 설명 포함)
✅ 이유: 무한 루프 방지. 3회는 "진짜 시도"에는 충분하고 "같은 실수 반복"은 걸러낼 수 있는 균형점입니다.
5
Language policy
version-control-language/language-policy
언어 사용 정책:
| 어디서 | 언어 |
|---|---|
| 코드, 변수명, 함수명, 주석 | 영어 |
| 커밋 메시지, 브랜치명 | 영어 |
| PR 설명, 코드리뷰 코멘트 | 한국어 (기술 용어는 영어) |
| 사용자 대면 UI 텍스트 | 한국어 |
✅ 이유: 코드는 글로벌 협업 가능성을 위해 영어, PR/코드리뷰는 팀 내 정확한 의사소통을 위해 한국어. 두 목적이 충돌하지 않습니다.
Rule 작성 가이드라인
| 좋은 rule | 나쁜rule |
|---|---|
| 명확한 행동 지침: "하라 / 하지 마라" | 모호한 지향: "더 나은 코드를 써라" |
| 짧고 구체적 (10줄 이내) | 지나치게 길어서 Claude가 일부만 따름 |
| 이유가 명확함 (why 포함) | 이유 없이 규칙만 나열 |
| 예외 케이스 명시 | 예외 없이 절대적 규칙 (현실에서 위반됨) |
| 단일 관심사 (one rule, one concern) | 여러 관심사를 한 rule에 묶음 |
⚠️ 과도한 제약 주의: Rule이 너무 엄격하면 Claude가 정상적인 작업도 못 하게 됩니다. "항상 이렇게 하라"보다 "특별한 이유 없으면 이렇게 하라"가 더 실용적입니다.
Claude가 Rule을 어떻게 따르는가
- TUI로 rule 설치 →
{project}/.agents/rules/에 복사 - CLAUDE.md의
managed block에 rule 파일 경로가 등록됨 - Claude Code 시작 시 managed block을 읽어 rules를 시스템 컨텍스트에 로드
- 모든 응답에서 자동 적용 — 사용자가 별도 언급 불필요
ℹ️ Rule은 "항상 켜진" 제약이므로 토큰을 계속 사용합니다. 24개 rule을 설치한 FE 하네스는 매 응답마다 수천 토큰을 컨텍스트에 추가합니다. 필요한 rule만 설치하는 것이 좋습니다.