Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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** - 새 기능에 적극적으로 사용, 테스트 먼저 작성을 강제