From b390fd141dd8dac71f68eb58825a6efeaddae84c Mon Sep 17 00:00:00 2001 From: hahmee Date: Sun, 8 Mar 2026 18:00:43 +0900 Subject: [PATCH] docs(ko-KR): add Korean translation for rules --- docs/ko-KR/rules/agents.md | 49 ++++++++++++++++++++++++++++ docs/ko-KR/rules/coding-style.md | 48 ++++++++++++++++++++++++++++ docs/ko-KR/rules/git-workflow.md | 24 ++++++++++++++ docs/ko-KR/rules/hooks.md | 30 +++++++++++++++++ docs/ko-KR/rules/patterns.md | 31 ++++++++++++++++++ docs/ko-KR/rules/performance.md | 55 ++++++++++++++++++++++++++++++++ docs/ko-KR/rules/security.md | 29 +++++++++++++++++ docs/ko-KR/rules/testing.md | 29 +++++++++++++++++ 8 files changed, 295 insertions(+) create mode 100644 docs/ko-KR/rules/agents.md create mode 100644 docs/ko-KR/rules/coding-style.md create mode 100644 docs/ko-KR/rules/git-workflow.md create mode 100644 docs/ko-KR/rules/hooks.md create mode 100644 docs/ko-KR/rules/patterns.md create mode 100644 docs/ko-KR/rules/performance.md create mode 100644 docs/ko-KR/rules/security.md create mode 100644 docs/ko-KR/rules/testing.md diff --git a/docs/ko-KR/rules/agents.md b/docs/ko-KR/rules/agents.md new file mode 100644 index 00000000..c26b8c53 --- /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.md new file mode 100644 index 00000000..bb6b68ca --- /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.md new file mode 100644 index 00000000..f3efb92b --- /dev/null +++ b/docs/ko-KR/rules/git-workflow.md @@ -0,0 +1,24 @@ +# Git 워크플로우 + +## 커밋 메시지 형식 +``` +: + +<선택적 본문> +``` + +타입: 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.md new file mode 100644 index 00000000..1f0c2dac --- /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.md new file mode 100644 index 00000000..5a3147b2 --- /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.md new file mode 100644 index 00000000..3252da8e --- /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.md new file mode 100644 index 00000000..a8d0bc5c --- /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.md new file mode 100644 index 00000000..a1d8d47d --- /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** - 새 기능에 적극적으로 사용, 테스트 먼저 작성을 강제