aiwf 0.3.23 → 0.4.0

package/docs/ADR_MANAGEMENT_GUIDE.ko.md

@@ -1,602 +0,0 @@
-# AIWF Architecture Decision Record (ADR) 관리 가이드
-
-> AIWF 프로젝트에서 ADR을 사용하여 아키텍처 결정을 관리하는 종합 가이드
-
-[한국어](ADR_MANAGEMENT_GUIDE.ko.md) | [English](ADR_MANAGEMENT_GUIDE.md)
-
-## 목차
-
-1. [ADR이란?](#adr이란)
-2. [AIWF에서 ADR을 사용하는 이유](#aiwf에서-adr을-사용하는-이유)
-3. [ADR 구조](#adr-구조)
-4. [AIWF와의 통합](#aiwf와의-통합)
-5. [ADR 생성](#adr-생성)
-6. [ADR 관리](#adr-관리)
-7. [ADR 템플릿](#adr-템플릿)
-8. [모범 사례](#모범-사례)
-9. [자동화 및 도구](#자동화-및-도구)
-10. [예제](#예제)
-
-## ADR이란?
-
-Architecture Decision Record(ADR)는 프로젝트에서 내려진 중요한 아키텍처 결정을 컨텍스트와 결과와 함께 기록하는 짧은 텍스트 문서입니다. 특정 결정이 내려진 이유의 역사적 기록 역할을 하며, 미래의 개발자들이 아키텍처 선택의 배경을 이해하는 데 도움을 줍니다.
-
-### 주요 특징
-
-- **불변성**: 작성된 후에는 변경되지 않음 (대체만 가능)
-- **번호 체계**: 쉬운 참조를 위한 순차적 번호 매기기
-- **풍부한 컨텍스트**: 결정에 이르게 된 상황 포함
-- **결과 인식**: 결과와 트레이드오프 문서화
-
-## AIWF에서 ADR을 사용하는 이유
-
-### AI 지원 개발의 이점
-
-1. **AI 컨텍스트**: Claude Code에 결정의 역사적 컨텍스트 제공
-2. **자율 가이던스**: YOLO 모드가 정보에 기반한 아키텍처 선택을 하도록 도움
-3. **일관성**: AI가 확립된 아키텍처 패턴을 따르도록 보장
-4. **문서화**: 개발 세션 간 아키텍처 지식 유지
-
-### AIWF 특화 장점
-
-- **스프린트 계획**: ADR이 태스크 생성과 우선순위에 정보 제공
-- **페르소나 컨텍스트**: 다른 AI 페르소나가 관련 결정 참조 가능
-- **품질 제어**: Engineering Guard가 결정 준수 여부 검증 가능
-- **복구**: 체크포인트 시스템이 컨텍스트 복원을 위해 ADR 참조 가능
-
-## ADR 구조
-
-### 표준 ADR 형식
-
-```markdown
-# ADR-001: 결정 제목
-
-**날짜**: YYYY-MM-DD
-**상태**: [제안됨 | 승인됨 | 폐기됨 | 대체됨]
-**컨텍스트**: AIWF 프로젝트 컨텍스트
-
-## 컨텍스트
-
-이 결정을 촉발한 문제나 상황에 대한 설명.
-
-## 결정
-
-내려진 아키텍처 결정.
-
-## 결과
-
-### 긍정적
-- 이 결정의 이점과 장점
-
-### 부정적
-- 단점과 트레이드오프
-
-### 중립적
-- 기타 효과와 고려사항
-
-## 구현 참고사항
-
-AIWF 내에서의 구현을 위한 구체적인 가이던스.
-
-## 관련 결정
-- 관련 ADR에 대한 링크
-- 영향받는 AIWF 구성요소에 대한 참조
-
-## 준수 검증
-- 이 결정에 대한 준수 여부를 확인하는 방법
-- 해당되는 경우 Engineering Guard 규칙
-```
-
-### AIWF 강화 구조
-
-```markdown
-# ADR-001: 결정 제목
-
-**날짜**: YYYY-MM-DD
-**상태**: 승인됨
-**컨텍스트**: AIWF v0.3.16+ 프로젝트
-**영향 범위**: [CLI | YOLO | Personas | Templates]
-**페르소나 관련성**: [architect | developer | security]
-
-## 컨텍스트
-[표준 컨텍스트 섹션]
-
-## 결정
-[표준 결정 섹션]
-
-## AIWF 통합
-
-### CLI 영향
-이 결정이 CLI 명령어와 워크플로에 미치는 영향.
-
-### YOLO 모드 고려사항
-자율 실행과 안전 메커니즘에 대한 의미.
-
-### 페르소나 가이드라인
-다른 AI 페르소나를 위한 구체적인 가이던스.
-
-### 템플릿 업데이트
-프로젝트 템플릿에 필요한 변경사항.
-
-## 결과
-[표준 결과 섹션]
-
-## 검증 규칙
-
-### Engineering Guard 규칙
-```yaml
-# .aiwf/yolo-config.yaml 추가사항
-custom_rules:
-  - name: "ADR-001 준수"
-    pattern: "validation_pattern"
-    severity: "warning"
-```
-
-### 자동화된 검사
-- 준수 검증을 위한 단위 테스트
-- CI/CD 파이프라인 검증
-- AIWF 명령어 통합
-
-## 구현 가이드
-
-### 단계별 구현
-1. [상세한 구현 단계]
-2. [AIWF 특화 고려사항]
-3. [검증 체크포인트]
-
-### 코드 예제
-```javascript
-// 구현 예제
-```
-
-## 관련 문서
-- [관련 AIWF 문서에 대한 링크]
-- [관련 ADR]
-- [AIWF 모듈 문서]
-```
-
-## AIWF와의 통합
-
-### 디렉토리 구조
-
-```
-.aiwf/
-├── adrs/
-│   ├── 0001-module-architecture.md
-│   ├── 0002-yolo-safety-mechanisms.md
-│   ├── 0003-persona-selection-strategy.md
-│   └── template.md
-├── yolo-config.yaml
-└── state.json
-```
-
-### AIWF 명령어 통합
-
-#### 계획된 명령어 (향후 개선)
-```bash
-# 새 ADR 생성
-aiwf adr create "데이터베이스 마이그레이션 전략"
-
-# ADR 목록
-aiwf adr list
-
-# 특정 ADR 표시
-aiwf adr show 001
-
-# 현재 작업에 ADR 연결
-aiwf adr link 001 --to-task T001
-
-# ADR에 대한 현재 코드 검증
-aiwf adr validate
-```
-
-### Claude Code 통합
-
-#### ADR 인식 명령어
-```markdown
-# Claude Code에서
-/aiwf_prime  # 이제 ADR 컨텍스트 로딩 포함
-/aiwf_create_milestone_plan  # 관련 ADR 참조
-/aiwf_yolo  # ADR 제약사항 고려
-```
-
-## ADR 생성
-
-### ADR을 생성해야 할 때
-
-1. **주요 아키텍처 변경**: 데이터베이스 스키마, API 설계, 모듈 구조
-2. **기술 선택**: 프레임워크 선택, 라이브러리 채택, 도구 통합
-3. **AIWF 특화 결정**: YOLO 동작, 페르소나 설정, 템플릿 설계
-4. **보안 결정**: 인증, 권한 부여, 데이터 보호
-5. **성능 결정**: 캐싱 전략, 최적화 접근법
-
-### 생성 과정
-
-#### 수동 생성
-```bash
-# 1. 템플릿 복사
-cp .aiwf/adrs/template.md .aiwf/adrs/0001-your-decision.md
-
-# 2. ADR 편집
-vim .aiwf/adrs/0001-your-decision.md
-
-# 3. 현재 작업에 연결
-# 태스크나 스프린트 문서에 ADR 참조 추가
-
-# 4. 커밋
-git add .aiwf/adrs/0001-your-decision.md
-git commit -m "docs: ADR-001 추가 for your decision"
-```
-
-#### AIWF 사용 (향후)
-```bash
-# 템플릿으로 생성
-aiwf adr create "마이크로서비스 통신 패턴"
-
-# 컨텍스트와 함께 생성
-aiwf adr create "YOLO 안전 메커니즘" --context="yolo-mode"
-
-# 페르소나 관점에서 생성
-aiwf adr create "보안 정책" --persona="security"
-```
-
-## ADR 관리
-
-### 생명주기 관리
-
-#### 상태 전환
-```
-제안됨 → 승인됨 → [폐기됨 | 대체됨]
-    ↓
- 거부됨
-```
-
-#### 상태 업데이트
-```markdown
-# ADR을 폐기하려면
-## 상태 업데이트
-**이전 상태**: 승인됨
-**새 상태**: 폐기됨
-**날짜**: 2025-01-27
-**이유**: ADR-015에 의해 대체됨
-```
-
-### 연결 및 참조
-
-#### 태스크 통합
-```markdown
-# 태스크 파일에서
-## 아키텍처 컨텍스트
-- ADR-001: 모듈 아키텍처 패턴
-- ADR-003: API 설계 원칙
-
-## 준수 요구사항
-- ADR-001 모듈 구조 따르기
-- ADR-003 오류 처리 구현
-```
-
-#### 스프린트 계획
-```markdown
-# 스프린트 문서에서
-## 고려할 아키텍처 결정
-- [ ] 데이터베이스 접근 패턴을 위해 ADR-002 검토
-- [ ] ADR-004 보안 가이드라인 적용
-- [ ] ADR-001 모듈 구조에 대한 검증
-```
-
-## ADR 템플릿
-
-### 기본 템플릿
-
-```markdown
-# ADR-{번호}: {제목}
-
-**날짜**: {날짜}
-**상태**: 제안됨
-**컨텍스트**: AIWF 프로젝트
-
-## 컨텍스트
-
-우리가 직면한 문제는 무엇인가? 어떤 요소들이 관련이 있는가?
-
-## 결정
-
-우리가 만드는 변화는 무엇인가?
-
-## 결과
-
-그 결과로 무엇이 더 쉬워지거나 어려워지는가?
-```
-
-### AIWF 특화 템플릿
-
-```markdown
-# ADR-{번호}: {제목}
-
-**날짜**: {날짜}
-**상태**: 제안됨
-**컨텍스트**: AIWF v{버전}+ 프로젝트
-**영향 범위**: [CLI | YOLO | Personas | Templates | Core]
-**페르소나 관련성**: [architect | developer | security | tester]
-
-## 컨텍스트
-
-### 문제 설명
-[아키텍처 챌린지에 대한 설명]
-
-### AIWF 컨텍스트
-[AIWF 워크플로 및 구성요소와의 관련성]
-
-### 제약사항
-[기술적, 비즈니스적, 또는 프로젝트 제약사항]
-
-## 결정
-
-### 선택된 접근법
-[내려진 아키텍처 결정]
-
-### 고려된 대안
-[평가된 다른 옵션들]
-
-### 근거
-[이 결정이 내려진 이유]
-
-## AIWF 통합
-
-### CLI 영향
-[명령줄 작업에 미치는 영향]
-
-### YOLO 모드 고려사항
-[자율 실행에 대한 의미]
-
-### 페르소나 가이드라인
-[다른 AI 페르소나를 위한 가이던스]
-
-### 템플릿 변경
-[프로젝트 템플릿에 필요한 업데이트]
-
-## 결과
-
-### 긍정적
-- [이점과 개선사항]
-
-### 부정적
-- [트레이드오프와 제한사항]
-
-### 중립적
-- [기타 효과]
-
-## 구현
-
-### 액션 아이템
-- [ ] [구체적인 구현 단계]
-- [ ] [AIWF 설정 업데이트]
-- [ ] [문서 업데이트]
-
-### 검증
-[올바른 구현을 확인하는 방법]
-
-### 일정
-[해당되는 경우 구현 일정]
-
-## 준수
-
-### Engineering Guard 규칙
-```yaml
-# .aiwf/yolo-config.yaml에 추가할 규칙
-adr_compliance:
-  adr_{번호}:
-    enabled: true
-    severity: warning
-    pattern: "{validation_pattern}"
-```
-
-### 자동화된 검사
-[단위 테스트, CI/CD 검증 등]
-
-## 관련 문서
-- [관련 문서에 대한 링크]
-- [관련 ADR]
-- [AIWF 모듈 참조]
-
-## 검토 및 승인
-
-### 검토자
-- [ ] 아키텍트: {이름}
-- [ ] 리드 개발자: {이름}
-- [ ] 보안 리드: {이름} (보안 관련인 경우)
-
-### 승인 날짜
-[ADR이 승인된 날짜]
-```
-
-## 모범 사례
-
-### 효과적인 ADR 작성
-
-1. **간결하게**: ADR을 집중되고 읽기 쉽게 유지
-2. **구체적으로**: 모호한 언어와 일반화 피하기
-3. **컨텍스트 포함**: 결정에 이르게 된 상황 설명
-4. **트레이드오프 문서화**: 결과에 대해 솔직하게 기술
-5. **코드에 연결**: 구체적인 구현 참조
-
-### AIWF 특화 모범 사례
-
-1. **페르소나 정렬**: 다른 페르소나가 ADR을 어떻게 해석할지 고려
-2. **YOLO 호환성**: 결정이 자율 실행과 호환되는지 확인
-3. **템플릿 통합**: 결정을 반영하여 프로젝트 템플릿 업데이트
-4. **Engineering Guard 규칙**: 해당되는 경우 검증 규칙 추가
-5. **스프린트 계획**: 태스크와 스프린트 문서에서 ADR 참조
-
-### 유지보수 관행
-
-1. **정기 검토**: 주기적으로 ADR 상태 검토 및 업데이트
-2. **링크 검증**: 참조가 정확한지 확인
-3. **구현 추적**: 결정 준수 모니터링
-4. **지식 전수**: 새 팀원 온보딩에 ADR 활용
-
-## 자동화 및 도구
-
-### Git 훅 통합
-
-```bash
-# .git/hooks/pre-commit
-#!/bin/bash
-# 커밋 메시지에서 ADR 참조 검증
-if git log -1 --pretty=%B | grep -q "ADR-[0-9]"; then
-    echo "✅ 커밋 메시지에서 ADR 참조 발견"
-else
-    echo "ℹ️  커밋 메시지에 관련 ADR 참조 고려하기"
-fi
-```
-
-### 향후 AIWF 통합
-
-#### 계획된 기능
-- **ADR 명령어**: `aiwf adr` 명령어 세트
-- **컨텍스트 로딩**: Claude Code에서 자동 ADR 컨텍스트
-- **검증**: Engineering Guard ADR 준수 검사
-- **템플릿**: ADR 인식 프로젝트 템플릿
-
-#### 제안된 워크플로
-```bash
-# 1. AIWF로 ADR 생성
-aiwf adr create "API 속도 제한 전략"
-
-# 2. 현재 작업에 연결
-aiwf task link ADR-001 --to-current
-
-# 3. 구현 검증
-aiwf adr validate --against=ADR-001
-
-# 4. 준수 리포트 생성
-aiwf adr report --sprint=S01
-```
-
-## 예제
-
-### 예제 1: 모듈 아키텍처 ADR
-
-```markdown
-# ADR-001: 모듈러 컴포넌트 아키텍처
-
-**날짜**: 2025-01-27
-**상태**: 승인됨
-**컨텍스트**: AIWF v0.3.16+ 프로젝트
-**영향 범위**: Core, CLI, Templates
-**페르소나 관련성**: architect, developer
-
-## 컨텍스트
-
-AIWF가 유기적으로 성장하면서 컴포넌트들이 긴밀하게 결합되어 개별 기능을 테스트, 유지보수, 확장하기 어려워졌습니다.
-
-## 결정
-
-명확한 의존성 경계를 가진 모듈러 아키텍처 채택:
-- 핵심 유틸리티 (paths, messages, language-utils)
-- 기능 모듈 (persona, checkpoint, compression)
-- 확장을 위한 플러그인 시스템
-
-## AIWF 통합
-
-### CLI 영향
-명령어들이 필요한 기능에 따라 모듈을 동적으로 로드합니다.
-
-### YOLO 모드 고려사항
-모듈러 설계로 YOLO가 필요한 컴포넌트만 로드하여 성능을 향상시킵니다.
-
-### Engineering Guard 규칙
-```yaml
-module_architecture:
-  enforce_boundaries: true
-  max_dependencies: 5
-  circular_dependency_check: true
-```
-
-## 결과
-
-### 긍정적
-- 향상된 테스트 가능성과 유지보수성
-- 더 빠른 개발 사이클
-- 더 나은 플러그인 지원
-
-### 부정적
-- 초기 복잡성 증가
-- 의존성 관리 필요
-
-## 구현
-- 기존 모놀리식 컴포넌트 리팩토링
-- 의존성 주입 구현
-- 문서 및 템플릿 업데이트
-```
-
-### 예제 2: YOLO 안전 메커니즘 ADR
-
-```markdown
-# ADR-002: YOLO 안전 메커니즘 프레임워크
-
-**날짜**: 2025-01-27
-**상태**: 승인됨
-**컨텍스트**: AIWF v0.3.16+ YOLO 모드
-**영향 범위**: YOLO, Engineering Guard, Checkpoint
-**페르소나 관련성**: architect, security
-
-## 컨텍스트
-
-자율 실행은 데이터 손실, 보안 문제, 코드 품질 저하를 방지하기 위한 강력한 안전 메커니즘이 필요합니다.
-
-## 결정
-
-다층 안전 프레임워크 구현:
-1. 코드 품질을 위한 Engineering Guard
-2. 복구를 위한 체크포인트 시스템
-3. 중요 작업을 위한 중단점 시스템
-4. 실시간 모니터링 및 개입
-
-## YOLO 모드 고려사항
-
-안전 프레임워크는 자율 실행을 위해 특별히 설계됨:
-- 논블로킹 품질 검사
-- 실패 시 자동 롤백
-- 개입의 점진적 에스컬레이션
-
-## Engineering Guard 규칙
-```yaml
-yolo_safety:
-  critical_file_protection: true
-  test_failure_threshold: 10
-  complexity_monitoring: true
-  automatic_checkpoints: 5
-```
-
-## 구현
-- YOLO 템플릿과 함께 engineering-guard.js 배포
-- 세션 추적과 checkpoint-manager.js 통합
-- yolo-config.yaml에 안전 설정 추가
-```
-
-## 관련 명령어
-
-### 현재 AIWF 명령어
-- `/aiwf_prime` - 프로젝트 컨텍스트 로드 (ADR 컨텍스트 포함 가능)
-- `/aiwf_create_milestone_plan` - 계획에서 ADR 참조
-- `/aiwf_do_task` - 구현 중 ADR 제약사항 고려
-
-### 계획된 명령어
-- `aiwf adr create` - 새 ADR 생성
-- `aiwf adr list` - 모든 ADR 목록
-- `aiwf adr validate` - ADR에 대한 코드 검증
-- `aiwf adr link` - ADR을 태스크에 연결
-
-## 관련 문서
-
-- [ARCHITECTURE.md](ARCHITECTURE.ko.md) - 전체 시스템 아키텍처
-- [MODULE_MANAGEMENT_GUIDE.md](MODULE_MANAGEMENT_GUIDE.ko.md) - 모듈 의존성 관리
-- [YOLO_SYSTEM_GUIDE.md](YOLO_SYSTEM_GUIDE.ko.md) - YOLO 모드 문서
-- [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.ko.md) - 개발 관행
-
----
-
-**마지막 업데이트**: 2025-01-27  
-**버전**: AIWF v0.3.16+ 호환  
-**상태**: 문서 프레임워크 (ADR 명령어는 구현 예정)