Work Execution Principles

작업 분할 원칙

• 모든 작업은 코드 리뷰가 가능한 크기의 의미있는 단위로 쪼갤 것
• "의미있는 단위"란: 독립적으로 테스트 가능하고, 명확한 목적이 있으며, 롤백이 가능한 변경 사항
• 큰 작업의 경우, 먼저 전체 구조를 설계한 뒤 단계별 실행 계획을 수립할 것
• 각 단계는 다음 기준을 만족해야 함:
  • 빌드/컴파일이 성공할 것
  • 기존 기능이 깨지지 않을 것
  • 가능하면 기능적으로 완결성이 있을 것

작업 시작 전 필수 단계

작업 범위 파악 및 검토 범위 결정

• 소규모 작업 (단일 함수 수정, 버그 픽스 등):
  • 수정할 파일과 그 파일이 직접 import/참조하는 파일만 확인
  • 해당 함수/컴포넌트의 사용처 1-2개 정도만 확인
• 중규모 작업 (새 기능 추가, 리팩토링 등):
  • 같은 도메인/모듈 내 관련 파일들 확인
  • 유사한 기능 구현 사례 검색 (1-2개)
  • 재사용 가능한 공용 모듈 존재 여부 확인
• 대규모 작업 (아키텍처 변경, 새 도메인 추가 등):
  • 프로젝트 전체 구조 파악
  • 관련된 모든 도메인/모듈 검토
  • 기존 패턴과 컨벤션 전반 확인

점진적 확장 원칙

• 처음에는 최소 범위만 검토하고 시작
• 작업 중 필요하다고 판단되면 그때 추가 검토
• 불필요한 사전 조사로 비용 낭비하지 말 것

파일 구조 검토

• 새 파일이 필요한지, 기존 파일에 추가할지 결정
• 파일이 300줄 이상이거나 관심사가 섞여 있으면 분리 고려
• 프로젝트 구조 컨벤션 준수

외부 라이브러리 사용 검토

• 복잡한 구현(날짜 처리, validation, 암호화, 파싱 등)은 검증된 라이브러리 우선 고려
• 직접 구현 시 테스트 코드가 지나치게 복잡해지는 경우 라이브러리 사용 권장
• 이미 프로젝트에서 사용 중인 라이브러리가 있는지 먼저 확인

구현 우선순위

• 기본 원칙: 성급한 구현보다 클린 코드 작성에 집중
  • 버그가 발생하지 않는 안정적인 코드
  • 유지보수가 쉬운 코드
  • 명확한 관심사 분리
• MVP 또는 빠른 기능 개발 모드:
  • 코드 완전성보다 기능 검증을 우선
  • 단, MVP를 검증 가능한 최소 단위로 명확히 정의할 것
  • 나중에 리팩토링하기 쉽도록 의미있는 단위로 모듈화는 유지
  • 추가 기능을 조금씩 덧댈 수 있는 구조 유지
• 섣부른 최적화 금지:
  • 명확한 성능 병목이 측정되기 전까지 최적화 자제
  • 가독성과 유지보수성을 희생하면서까지 최적화하지 말 것
  • "미래에 필요할 것 같아서" 미리 추상화하지 말 것

테스트 전략

• 대부분의 코드는 단위 테스트가 가능한 구조로 작성할 것
• MVP 개발을 제외하고는 테스트 코드를 병행하면서 개발할 것
  • 테스트와 함께 개발하면 자연스럽게 테스트 가능한 구조가 됨
  • 나중에 테스트를 추가하려면 코드가 엇나가는 경우가 많음
• 테스트하기 어려운 코드는 구조적 문제의 신호:
  • 전역 상태에 의존하는 경우
  • 사이드 이펙트가 명확히 분리되지 않은 경우
  • 하나의 함수가 너무 많은 일을 하는 경우

의존성 관리

• 전역 변수, 싱글톤 인스턴스 직접 참조 금지
• 의존성 주입 원칙 준수:
  • 필요한 의존성은 생성자, 함수 파라미터 등을 통해 주입
  • 테스트 시 mock 객체로 쉽게 대체 가능하도록
  • 예외: 순수 유틸리티 함수, 상수 등
• 의존성 방향은 항상 안정적인 쪽으로:
  • 구체적인 것이 추상적인 것에 의존
  • 상위 레벨이 하위 레벨에 의존하지 않도록

작업 완료 후

• 작업 완료 시 WORK_SUMMARY.md 파일 생성하여 다음 내용 포함:
  • 수행한 작업 목록 (일목요연하게)
  • 변경된 주요 파일 및 변경 이유
  • 기능 테스트 방법 (실제로 어떻게 확인할 수 있는지)
  • 주의사항이나 알아야 할 제약사항
• 중간 진행 상황은 간결하게 텍스트로만 보고
• 새 기능이 추가되거나, 비즈니스 로직이 크게 변경된 경우, 알아서 README.md 나 CLAUDE.md 같은 전역적인 문서 수정하고 보고할 것