JikiME-ADK Contexts Reference
JikiME-ADK의 컨텍스트 시스템 문서입니다.
개요
컨텍스트(Context)는 Claude의 동작 모드를 정의합니다. 상황에 따라 적절한 컨텍스트가 자동 로드되거나 수동으로 전환할 수 있습니다.
컨텍스트 맵
┌─────────────────────────────────────────────────────────────────┐
│ JikiME-ADK Contexts │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Development Contexts ────────────────────────────────────┐ │
│ │ │ │
│ │ dev.md 개발 모드 (코드 우선) │ │
│ │ planning.md 계획 모드 (생각 우선) │ │
│ │ debug.md 디버그 모드 (조사) │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Review & Sync Contexts ──────────────────────────────────┐ │
│ │ │ │
│ │ review.md 리뷰 모드 (품질 중심) │ │
│ │ sync.md 동기화 모드 (문서 우선) │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Research Context ────────────────────────────────────────┐ │
│ │ │ │
│ │ research.md 연구 모드 (이해 우선) │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘자동 로드 매핑
| 명령어 | 자동 로드 컨텍스트 |
|---|---|
/jikime:0-project | research.md |
/jikime:1-plan | planning.md |
/jikime:2-run | dev.md |
/jikime:3-sync | sync.md |
/jikime:build-fix | debug.md |
/jikime:learn | research.md |
dev.md - 개발 컨텍스트
Mode: Active Development Focus: Implementation, coding, building features Methodology: DDD (ANALYZE → PRESERVE → IMPROVE)
핵심 원칙
1. Get it working → 먼저 동작하게
2. Get it right → 그 다음 정확하게
3. Get it clean → 마지막으로 깔끔하게행동 규칙
| DO | DON'T |
|---|---|
| 코드 먼저, 설명은 나중에 | 간단한 솔루션 과도하게 설계 |
| 완벽보다 작동하는 솔루션 우선 | 요청하지 않은 기능 추가 |
| 변경 후 테스트 실행 | 에러 처리 생략 |
| 원자적 커밋 유지 | 프로덕션 코드에 console.log |
| 기존 코드 패턴 따르기 | 기존 테스트 무시 |
DDD 사이클
기존 코드 수정 전:
ANALYZE → 현재 동작 이해
PRESERVE → 기존 동작 테스트로 보장
IMPROVE → 점진적으로 변경 구현도구 우선순위
| 우선순위 | 도구 | 용도 |
|---|---|---|
| 1 | Edit | 기존 파일 수정 |
| 2 | Write | 새 파일 생성 |
| 3 | Bash | 테스트, 빌드, 명령 실행 |
| 4 | Grep/Glob | 코드 패턴 찾기 |
| 5 | Read | 편집 전 이해 |
코딩 표준
yaml
files:
max_lines: 400
organization: by_feature
functions:
max_lines: 50
max_nesting: 4
single_responsibility: true
error_handling:
explicit: true
user_friendly_messages: true
testing:
write_tests: after_implementation
coverage_target: 80%전환 가이드
@contexts/planning.md→ 복잡한 작업 시작 전@contexts/debug.md→ 에러에 막혔을 때@contexts/review.md→ 커밋 전
planning.md - 계획 컨텍스트
Mode: Strategic Planning & Design Focus: Think before code, plan before act Principle: Measure twice, cut once
핵심 원칙
1. Understand scope → 무엇을 해야 하는지 명확히
2. Identify risks → 잠재적 문제 미리 파악
3. Break into phases → 작은 단위로 분해
4. Get confirmation → 진행 전 승인 필요행동 규칙
| DO | DON'T |
|---|---|
| 요구사항 철저히 분석 | 계획 승인 전 코딩 시작 |
| 의존성/블로커 식별 | 리스크 평가 생략 |
| 여러 접근 방식 고려 | 복잡도 과소평가 |
| 복잡도 정직하게 추정 | 기존 패턴 무시 |
| 가정 문서화 | 가정을 기록하지 않음 |
| 사용자 확인 대기 |
계획 프로세스
┌─────────────────────────────────────────┐
│ Planning Workflow │
├─────────────────────────────────────────┤
│ 1. UNDERSTAND │
│ └─ What exactly needs to be done? │
│ ↓ │
│ 2. ANALYZE │
│ └─ What exists? What's affected? │
│ ↓ │
│ 3. DESIGN │
│ └─ How should we approach this? │
│ ↓ │
│ 4. DECOMPOSE │
│ └─ Break into manageable phases │
│ ↓ │
│ 5. ASSESS │
│ └─ Risks, dependencies, complexity │
│ ↓ │
│ 6. PRESENT │
│ └─ Show plan, wait for approval │
└─────────────────────────────────────────┘복잡도 추정
| 레벨 | 특성 |
|---|---|
| LOW | 단일 파일, < 100줄, 의존성 없음 |
| MEDIUM | 2-5개 파일, < 500줄, 일부 의존성 |
| HIGH | 5개+ 파일, 아키텍처 변경, 외부 의존성 |
리스크 평가 매트릭스
| 확률 \ 영향 | LOW | MEDIUM | HIGH |
|---|---|---|---|
| HIGH | ⚠️ 모니터링 | 🔶 Plan B | 🔴 차단 |
| MEDIUM | ✅ 수용 | ⚠️ 모니터링 | 🔶 Plan B |
| LOW | ✅ 수용 | ✅ 수용 | ⚠️ 모니터링 |
전환 가이드
@contexts/research.md→ 먼저 더 이해해야 할 때@contexts/dev.md→ 계획 승인 후 코딩 준비@contexts/review.md→ 시작 전 계획 검토
debug.md - 디버그 컨텍스트
Mode: Problem Investigation & Resolution Focus: Root cause analysis, systematic debugging Principle: Hypothesize → Test → Verify
핵심 원칙
1. Reproduce first → 문제 재현 확인
2. Isolate the issue → 원인 범위 좁히기
3. Find root cause → 표면 증상이 아닌 근본 원인
4. Verify the fix → 수정 후 재발 방지 확인행동 규칙
| DO | DON'T |
|---|---|
| 조사 전 버그 재현 | 증거 없이 추측 |
| 에러 메시지 주의 깊게 읽기 | 원인 이해 없이 수정 적용 |
| 최근 변경 확인 (git log/diff) | 스택 트레이스 무시 |
| 이진 검색으로 문제 격리 | 재현 단계 생략 |
| 수정이 다른 것을 깨지 않는지 확인 | 근본 원인 대신 증상 수정 |
디버그 프로세스
┌─────────────────────────────────────────┐
│ Debug Workflow │
├─────────────────────────────────────────┤
│ 1. REPRODUCE │
│ └─ Can we consistently trigger it? │
│ ↓ │
│ 2. GATHER INFO │
│ └─ Error messages, logs, stack │
│ ↓ │
│ 3. HYPOTHESIZE │
│ └─ What could cause this? │
│ ↓ │
│ 4. ISOLATE │
│ └─ Binary search to narrow scope │
│ ↓ │
│ 5. ROOT CAUSE │
│ └─ Why does this happen? │
│ ↓ │
│ 6. FIX & VERIFY │
│ └─ Fix and confirm resolution │
└─────────────────────────────────────────┘일반적인 버그 패턴
| 증상 | 예상 원인 | 확인 방법 |
|---|---|---|
| "undefined is not..." | Null 참조 | Optional chaining, null 체크 |
| 무한 루프 | 종료 조건 누락 | 루프 조건, 재귀 베이스 |
| 레이스 컨디션 | Async 타이밍 | await, Promise 처리 |
| 잘못된 데이터 | 타입 불일치 | 입력 검증, 타입 강제 변환 |
| 조용한 실패 | 삼켜진 에러 | try/catch, 에러 처리 |
빠른 디버깅 체크리스트
markdown
□ 일관되게 재현할 수 있는가?
□ 전체 에러 메시지를 읽었는가?
□ 스택 트레이스를 확인했는가?
□ 최근 무엇이 변경되었는가?
□ 입력 데이터가 정확한가?
□ 모든 의존성이 로드되었는가?
□ async/await가 올바르게 처리되는가?
□ null/undefined 값이 있는가?전환 가이드
@contexts/dev.md→ 수정 구현 준비@contexts/research.md→ 시스템을 더 이해해야 할 때@contexts/review.md→ 수정 품질 검증
review.md - 리뷰 컨텍스트
Mode: Quality Analysis & PR Review Focus: Security, maintainability, correctness Principle: Suggest fixes, don't just criticize
핵심 원칙
1. Read thoroughly → 전체 맥락 파악
2. Prioritize issues → 심각도별 분류
3. Suggest fixes → 문제만 지적 X, 해결책 제시
4. Be constructive → 비판이 아닌 개선 제안행동 규칙
| DO | DON'T |
|---|---|
| 코멘트 전 모든 변경 읽기 | 가독성 영향 없는 스타일 지적 |
| 심각도별 우선순위 지정 | 사소한 이슈로 PR 차단 |
| 실행 가능한 수정 제안 제공 | 대안 없이 비판 |
| 보안 취약점 확인 | 더 넓은 맥락 무시 |
| 변경에 대한 테스트 커버리지 확인 | 보안 검사 생략 |
| 좋은 패턴 인정 |
리뷰 체크리스트
Security (CRITICAL)
- 하드코딩된 시크릿/자격증명 없음
- 입력 검증 존재
- SQL Injection 방지
- XSS 보호
- 인증/권한 확인
- 민감 데이터 처리
Logic (HIGH)
- 엣지 케이스 처리
- 에러 처리 완료
- Null/undefined 체크
- 레이스 컨디션 고려
- 비즈니스 로직 정확성
Quality (MEDIUM)
- 코드 가독성
- 함수 크기 (< 50줄)
- 중첩 깊이 (< 4단계)
- DRY 원칙 준수
- 네이밍 컨벤션
Testing (MEDIUM)
- 새 코드에 테스트 있음
- 엣지 케이스 테스트됨
- 기존 테스트 여전히 통과
- 커버리지 유지됨
Performance (LOW)
- 명백한 병목 없음
- 효율적 알고리즘
- 메모리 고려
- N+1 쿼리 방지
심각도 정의
| 레벨 | 영향 | 필요 조치 |
|---|---|---|
| CRITICAL | 보안 위반, 데이터 손실 | 머지 차단, 즉시 수정 |
| HIGH | 버그, 크래시, 로직 오류 | 머지 전 수정 |
| MEDIUM | 유지보수성, 품질 | 수정 권장, 머지 가능 |
| LOW | 스타일, 사소한 개선 | 선택, 있으면 좋음 |
전환 가이드
@contexts/dev.md→ 이슈 수정 준비@contexts/research.md→ 더 이해가 필요@contexts/debug.md→ 특정 버그 조사
research.md - 연구 컨텍스트
Mode: Exploration & Investigation Focus: Understanding before acting Principle: Read widely, conclude carefully
핵심 원칙
1. Understand first → 질문을 정확히 이해
2. Explore broadly → 관련 코드/문서 탐색
3. Verify evidence → 가설을 증거로 검증
4. Summarize clearly → 발견 사항 정리행동 규칙
| DO | DON'T |
|---|---|
| 결론 전 철저히 읽기 | 이해가 명확해지기 전 코드 작성 |
| 불확실할 때 명확화 질문 | 증거 없이 결론 도출 |
| 발견하면서 문서화 | 엣지 케이스나 예외 무시 |
| 여러 소스 교차 참조 | 검증 없이 가정 |
| 불확실성과 가정 기록 | 문서 검토 생략 |
연구 프로세스
┌─────────────────────────────────────────┐
│ Research Workflow │
├─────────────────────────────────────────┤
│ 1. QUESTION │
│ └─ Clarify what we need to know │
│ ↓ │
│ 2. EXPLORE │
│ └─ Search code, docs, patterns │
│ ↓ │
│ 3. HYPOTHESIZE │
│ └─ Form initial understanding │
│ ↓ │
│ 4. VERIFY │
│ └─ Test hypothesis with evidence │
│ ↓ │
│ 5. DOCUMENT │
│ └─ Record findings and gaps │
└─────────────────────────────────────────┘도구 우선순위
| 우선순위 | 도구 | 용도 |
|---|---|---|
| 1 | Read | 특정 파일 깊이 탐구 |
| 2 | Grep | 코드베이스 전체 패턴 찾기 |
| 3 | Glob | 패턴으로 파일 위치 찾기 |
| 4 | Task (Explore) | 폭넓은 코드베이스 질문 |
| 5 | WebSearch | 외부 문서 |
| 6 | WebFetch | URL 확인, 상세 정보 얻기 |
증거 표준
| 주장 유형 | 필요한 증거 |
|---|---|
| "X가 Y를 한다" | 라인 번호가 있는 코드 참조 |
| "패턴이 Z이다" | 코드베이스에서 3개 이상 예시 |
| "모범 사례" | 공식 문서 또는 확립된 관례 |
| "성능" | 벤치마크 또는 프로파일링 데이터 |
전환 가이드
@contexts/planning.md→ 구현 계획 준비@contexts/dev.md→ 코딩 준비@contexts/debug.md→ 버그 조사
sync.md - 동기화 컨텍스트
Mode: Documentation Synchronization Focus: Document generation, quality verification, git operations Methodology: Sync → Verify → Commit
핵심 원칙
1. Analyze changes → 변경된 코드 분석
2. Update docs → 문서 동기화
3. Verify quality → 품질 검증
4. Commit changes → 변경사항 커밋행동 규칙
| DO | DON'T |
|---|---|
| 동기화 전 git 변경 분석 | 변경되지 않은 문서 재생성 |
| 영향받는 문서만 업데이트 | 품질 검증 생략 |
| 동기화 후 링크 무결성 확인 | 리뷰 옵션 없이 커밋 |
| TRUST 5 원칙 따르기 | 불필요한 문서 생성 |
| 의미있는 커밋 메시지 작성 | 기존 문서 링크 깨뜨리기 |
| 전문 에이전트에게 위임 |
동기화 단계
PHASE 0.5: Quality Verification
↓
PHASE 1: Analysis & Planning
↓
PHASE 2: Execute Sync
↓
PHASE 3: Git Operations에이전트 위임
yaml
manager-docs:
purpose: 문서 생성 및 업데이트
tasks:
- README 동기화
- CODEMAP 업데이트
- SPEC 상태 동기화
- API 문서화
manager-quality:
purpose: 품질 검증
tasks:
- TRUST 5 준수 확인
- 링크 무결성 검증
- 일관성 확인
manager-git:
purpose: Git 작업
tasks:
- 문서 파일 스테이징
- 커밋 생성
- PR 관리 (Team 모드)TRUST 5 체크리스트
T - Tested: 모든 링크 작동
R - Readable: 명확한 구조, 적절한 포맷팅
U - Unified: 일관된 용어
S - Secured: 민감 데이터 노출 없음
T - Trackable: 버전 정보, 타임스탬프전환 가이드
@contexts/dev.md→ 개발 계속@contexts/review.md→ 동기화 전 코드 리뷰@contexts/planning.md→ 다음 기능 계획
컨텍스트 전환 가이드
수동 전환
bash
@.claude/contexts/dev.md 모드로 구현해줘
@.claude/contexts/debug.md 이 에러 분석해줘
@.claude/contexts/planning.md 이 기능 계획해줘컨텍스트 흐름
┌─────────────┐
│ research │ ← 시작점 (이해 필요)
└──────┬──────┘
│
▼
┌─────────────┐
│ planning │ ← 계획 수립
└──────┬──────┘
│
▼
┌─────────────┐
│ dev │ ← 구현
└──────┬──────┘
│
┌────────┴────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ debug │ │ review │
└──────────┘ └────┬─────┘
│ │
└────────┬───────┘
│
▼
┌─────────────┐
│ sync │ ← 완료 및 문서화
└─────────────┘컨텍스트 비교
| 컨텍스트 | 목적 | 코드 작성 | 주요 도구 |
|---|---|---|---|
| research | 이해 | ❌ | Read, Grep, WebSearch |
| planning | 계획 | ❌ | Read, Grep, AskUser |
| dev | 구현 | ✅ | Edit, Write, Bash |
| debug | 조사 | 수정만 | Read, Grep, LSP |
| review | 검증 | ❌ | Read, Grep, git diff |
| sync | 문서화 | 문서만 | Task, Write, Bash |
Version: 1.0.0 Last Updated: 2026-01-22