The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(ko-KR): add Korean translation for rules
hahmeeb390fd141dd8
diff --git a/docs/ko-KR/rules/agents.md b/docs/ko-KR/rules/agents.mdnew file mode 100644index 000000000..c26b8c535--- /dev/null+++ b/docs/ko-KR/rules/agents.md@@ -0,0 +1,49 @@+# 에이전트 오케스트레이션++## 사용 가능한 에이전트++`~/.claude/agents/`에 위치:++| 에이전트 | 용도 | 사용 시점 |+|---------|------|----------|+| planner | 구현 계획 | 복잡한 기능, 리팩토링 |+| architect | 시스템 설계 | 아키텍처 의사결정 |+| tdd-guide | 테스트 주도 개발 | 새 기능, 버그 수정 |+| code-reviewer | 코드 리뷰 | 코드 작성 후 |+| security-reviewer | 보안 분석 | 커밋 전 |+| build-error-resolver | 빌드 에러 수정 | 빌드 실패 시 |+| e2e-runner | E2E 테스팅 | 핵심 사용자 흐름 |+| refactor-cleaner | 사용하지 않는 코드 정리 | 코드 유지보수 |+| doc-updater | 문서 관리 | 문서 업데이트 |++## 즉시 에이전트 사용++사용자 프롬프트 불필요:+1. 복잡한 기능 요청 - **planner** 에이전트 사용+2. 코드 작성/수정 직후 - **code-reviewer** 에이전트 사용+3. 버그 수정 또는 새 기능 - **tdd-guide** 에이전트 사용+4. 아키텍처 의사결정 - **architect** 에이전트 사용++## 병렬 Task 실행++독립적인 작업에는 항상 병렬 Task 실행 사용:++```markdown+# 좋음: 병렬 실행+3개 에이전트를 병렬로 실행:+1. 에이전트 1: 인증 모듈 보안 분석+2. 에이전트 2: 캐시 시스템 성능 리뷰+3. 에이전트 3: 유틸리티 타입 검사++# 나쁨: 불필요하게 순차 실행+먼저 에이전트 1, 그다음 에이전트 2, 그다음 에이전트 3+```++## 다중 관점 분석++복잡한 문제에는 역할 분리 서브에이전트 사용:+- 사실 검증 리뷰어+- 시니어 엔지니어+- 보안 전문가+- 일관성 검토자+- 중복 검사자diff --git a/docs/ko-KR/rules/coding-style.md b/docs/ko-KR/rules/coding-style.mdnew file mode 100644index 000000000..bb6b68ca9--- /dev/null+++ b/docs/ko-KR/rules/coding-style.md@@ -0,0 +1,48 @@+# 코딩 스타일++## 불변성 (중요)++항상 새 객체를 생성하고, 기존 객체를 절대 변경하지 마세요:++```+// 의사 코드+잘못된 예: modify(original, field, value) → 원본을 직접 변경+올바른 예: update(original, field, value) → 변경 사항이 반영된 새 복사본 반환+```++근거: 불변 데이터는 숨겨진 사이드 이펙트를 방지하고, 디버깅을 쉽게 하며, 안전한 동시성을 가능하게 합니다.++## 파일 구성++많은 작은 파일 > 적은 큰 파일:+- 높은 응집도, 낮은 결합도+- 200-400줄이 일반적, 최대 800줄+- 큰 모듈에서 유틸리티를 분리+- 타입이 아닌 기능/도메인별로 구성++## 에러 처리++항상 에러를 포괄적으로 처리:+- 모든 레벨에서 에러를 명시적으로 처리+- UI 코드에서는 사용자 친화적인 에러 메시지 제공+- 서버 측에서는 상세한 에러 컨텍스트 로깅+- 에러를 절대 조용히 무시하지 않기++## 입력 유효성 검증++항상 시스템 경계에서 유효성 검증:+- 처리 전에 모든 사용자 입력을 검증+- 가능한 경우 스키마 기반 유효성 검증 사용+- 명확한 에러 메시지와 함께 빠르게 실패+- 외부 데이터를 절대 신뢰하지 않기 (API 응답, 사용자 입력, 파일 내용)++## 코드 품질 체크리스트++작업 완료 전 확인:+- [ ] 코드가 읽기 쉽고 이름이 적절한가+- [ ] 함수가 작은가 (<50줄)+- [ ] 파일이 집중적인가 (<800줄)+- [ ] 깊은 중첩이 없는가 (>4단계)+- [ ] 적절한 에러 처리가 되어 있는가+- [ ] 하드코딩된 값이 없는가 (상수나 설정 사용)+- [ ] 변이가 없는가 (불변 패턴 사용)diff --git a/docs/ko-KR/rules/git-workflow.md b/docs/ko-KR/rules/git-workflow.mdnew file mode 100644index 000000000..f3efb92bf--- /dev/null+++ b/docs/ko-KR/rules/git-workflow.md@@ -0,0 +1,24 @@+# Git 워크플로우++## 커밋 메시지 형식+```+<type>: <description>++<선택적 본문>+```++타입: feat, fix, refactor, docs, test, chore, perf, ci++참고: 어트리뷰션은 ~/.claude/settings.json에서 전역적으로 비활성화되어 있습니다.++## Pull Request 워크플로우++PR을 만들 때:+1. 전체 커밋 히스토리를 분석 (최신 커밋만이 아닌)+2. `git diff [base-branch]...HEAD`로 모든 변경사항 확인+3. 포괄적인 PR 요약 작성+4. TODO가 포함된 테스트 계획 포함+5. 새 브랜치인 경우 `-u` 플래그와 함께 push++> git 작업 전 전체 개발 프로세스(계획, TDD, 코드 리뷰)는+> [development-workflow.md](./development-workflow.md)를 참고하세요.diff --git a/docs/ko-KR/rules/hooks.md b/docs/ko-KR/rules/hooks.mdnew file mode 100644index 000000000..1f0c2daca--- /dev/null+++ b/docs/ko-KR/rules/hooks.md@@ -0,0 +1,30 @@+# 훅 시스템++## 훅 유형++- **PreToolUse**: 도구 실행 전 (유효성 검증, 매개변수 수정)+- **PostToolUse**: 도구 실행 후 (자동 포맷, 검사)+- **Stop**: 세션 종료 시 (최종 검증)++## 자동 수락 권한++주의하여 사용:+- 신뢰할 수 있는, 잘 정의된 계획에서만 활성화+- 탐색적 작업에서는 비활성화+- dangerously-skip-permissions 플래그를 절대 사용하지 않기+- 대신 `~/.claude.json`에서 `allowedTools`를 설정++## TodoWrite 모범 사례++TodoWrite 도구 활용:+- 다단계 작업의 진행 상황 추적+- 지시사항 이해도 검증+- 실시간 방향 조정 가능+- 세부 구현 단계 표시++Todo 목록으로 확인 가능한 것:+- 순서가 맞지 않는 단계+- 누락된 항목+- 불필요한 추가 항목+- 잘못된 세분화 수준+- 잘못 해석된 요구사항diff --git a/docs/ko-KR/rules/patterns.md b/docs/ko-KR/rules/patterns.mdnew file mode 100644index 000000000..5a3147b2c--- /dev/null+++ b/docs/ko-KR/rules/patterns.md@@ -0,0 +1,31 @@+# 공통 패턴++## 스켈레톤 프로젝트++새 기능을 구현할 때:+1. 검증된 스켈레톤 프로젝트를 검색+2. 병렬 에이전트로 옵션 평가:+ - 보안 평가+ - 확장성 분석+ - 관련성 점수+ - 구현 계획+3. 가장 적합한 것을 기반으로 클론+4. 검증된 구조 내에서 반복 개선++## 디자인 패턴++### 리포지토리 패턴++일관된 인터페이스 뒤에 데이터 접근을 캡슐화:+- 표준 작업 정의: findAll, findById, create, update, delete+- 구체적 구현이 저장소 세부사항 처리 (데이터베이스, API, 파일 등)+- 비즈니스 로직은 저장소 메커니즘이 아닌 추상 인터페이스에 의존+- 데이터 소스의 쉬운 교체 및 모킹을 통한 테스트 단순화 가능++### API 응답 형식++모든 API 응답에 일관된 엔벨로프 사용:+- 성공/상태 표시자 포함+- 데이터 페이로드 포함 (에러 시 null)+- 에러 메시지 필드 포함 (성공 시 null)+- 페이지네이션 응답에 메타데이터 포함 (total, page, limit)diff --git a/docs/ko-KR/rules/performance.md b/docs/ko-KR/rules/performance.mdnew file mode 100644index 000000000..3252da8e1--- /dev/null+++ b/docs/ko-KR/rules/performance.md@@ -0,0 +1,55 @@+# 성능 최적화++## 모델 선택 전략++**Haiku 4.5** (Sonnet 능력의 90%, 3배 비용 절감):+- 자주 호출되는 경량 에이전트+- 페어 프로그래밍과 코드 생성+- 멀티 에이전트 시스템의 워커 에이전트++**Sonnet 4.6** (최고의 코딩 모델):+- 주요 개발 작업+- 멀티 에이전트 워크플로우 오케스트레이션+- 복잡한 코딩 작업++**Opus 4.5** (가장 깊은 추론):+- 복잡한 아키텍처 의사결정+- 최대 추론 요구사항+- 리서치 및 분석 작업++## 컨텍스트 윈도우 관리++컨텍스트 윈도우의 마지막 20%에서는 다음을 피하세요:+- 대규모 리팩토링+- 여러 파일에 걸친 기능 구현+- 복잡한 상호작용 디버깅++컨텍스트 민감도가 낮은 작업:+- 단일 파일 수정+- 독립적인 유틸리티 생성+- 문서 업데이트+- 단순한 버그 수정++## 확장 사고 + 계획 모드++확장 사고는 기본적으로 활성화되어 있으며, 내부 추론을 위해 최대 31,999 토큰을 예약합니다.++확장 사고 제어 방법:+- **전환**: Option+T (macOS) / Alt+T (Windows/Linux)+- **설정**: `~/.claude/settings.json`에서 `alwaysThinkingEnabled` 설정+- **예산 제한**: `export MAX_THINKING_TOKENS=10000`+- **상세 모드**: Ctrl+O로 사고 출력 확인++깊은 추론이 필요한 복잡한 작업:+1. 확장 사고가 활성화되어 있는지 확인 (기본 활성)+2. 구조적 접근을 위해 **계획 모드** 활성화+3. 철저한 분석을 위해 여러 라운드의 비판 수행+4. 다양한 관점을 위해 역할 분리 서브에이전트 사용++## 빌드 문제 해결++빌드 실패 시:+1. **build-error-resolver** 에이전트 사용+2. 에러 메시지 분석+3. 점진적으로 수정+4. 각 수정 후 검증diff --git a/docs/ko-KR/rules/security.md b/docs/ko-KR/rules/security.mdnew file mode 100644index 000000000..a8d0bc5cd--- /dev/null+++ b/docs/ko-KR/rules/security.md@@ -0,0 +1,29 @@+# 보안 가이드라인++## 필수 보안 점검++모든 커밋 전:+- [ ] 하드코딩된 시크릿이 없는가 (API 키, 비밀번호, 토큰)+- [ ] 모든 사용자 입력이 검증되었는가+- [ ] SQL 인젝션 방지가 되었는가 (매개변수화된 쿼리)+- [ ] XSS 방지가 되었는가 (HTML 새니타이징)+- [ ] CSRF 보호가 활성화되었는가+- [ ] 인증/인가가 검증되었는가+- [ ] 모든 엔드포인트에 속도 제한이 있는가+- [ ] 에러 메시지가 민감한 데이터를 노출하지 않는가++## 시크릿 관리++- 소스 코드에 시크릿을 절대 하드코딩하지 않기+- 항상 환경 변수나 시크릿 매니저 사용+- 시작 시 필요한 시크릿이 존재하는지 검증+- 노출되었을 수 있는 시크릿은 교체++## 보안 대응 프로토콜++보안 이슈 발견 시:+1. 즉시 중단+2. **security-reviewer** 에이전트 사용+3. 계속 진행하기 전에 치명적 이슈 수정+4. 노출된 시크릿 교체+5. 유사한 이슈가 있는지 전체 코드베이스 검토diff --git a/docs/ko-KR/rules/testing.md b/docs/ko-KR/rules/testing.mdnew file mode 100644index 000000000..a1d8d47d8--- /dev/null+++ b/docs/ko-KR/rules/testing.md@@ -0,0 +1,29 @@+# 테스팅 요구사항++## 최소 테스트 커버리지: 80%++테스트 유형 (모두 필수):+1. **단위 테스트** - 개별 함수, 유틸리티, 컴포넌트+2. **통합 테스트** - API 엔드포인트, 데이터베이스 작업+3. **E2E 테스트** - 핵심 사용자 흐름 (언어별 프레임워크 선택)++## 테스트 주도 개발++필수 워크플로우:+1. 테스트를 먼저 작성 (RED)+2. 테스트 실행 - 실패해야 함+3. 최소한의 구현 작성 (GREEN)+4. 테스트 실행 - 통과해야 함+5. 리팩토링 (IMPROVE)+6. 커버리지 확인 (80% 이상)++## 테스트 실패 문제 해결++1. **tdd-guide** 에이전트 사용+2. 테스트 격리 확인+3. 모킹이 올바른지 검증+4. 테스트가 아닌 구현을 수정 (테스트가 잘못된 경우 제외)++## 에이전트 지원++- **tdd-guide** - 새 기능에 적극적으로 사용, 테스트 먼저 작성을 강제