사양을 먼저 쓰고, 테스트부터 시작하는 작은 단위로 개발하기

## 불분명한 요구 사항은 질문으로 기록하고 답이 나올 때까지 계획하지 않기 중대한 요구사항이 불명확한 상태에서는 계획하거나 구현하지 마세요. 변경을 제안하기 전에 미해결 요구사항, 비기능 기대사항, 동작, 텔레메트리, 정책, 인수 기준을 식별하세요. 영향도가 높은 모든 확인 사항과 영향도가 중간인 각 불확실성을 결정을 요청하기 전에 저장소에서 지정한 미해결 질문 등록부에 기록하세요. 각 질문에 안정적인 식별자를 부여하고, 해결될 때까지 기준 사양, 계획, 작업 목록의 범위를 해당 식별자에 맞추세요. 대안을 제시할 때는 먼저 동일한 선택지를 기록한 다음 사용자에게 직접 요약하세요. 권장 선택지를 첫 번째로 배치하고, 간결한 장단점을 제시하며, 질문 식별자를 인용한 뒤 필요한 답변을 받을 때까지 중단하세요. 해결되면 답변을 사양의 규범적 섹션에 반영하고 등록부 항목을 닫으세요. ## 계획 전에 사양과 아키텍처 맵 읽기 저장소 루트에서 작업하고 저장소 전체 지침과 관련된 모든 중첩 규칙을 적용하세요. 계획하기 전에 현재 로드맵, 기준 기능 사양, 모듈 또는 지식 맵, 코딩 규칙, 영향을 받는 기능과 연결된 아키텍처 결정을 읽으세요. 변경이 영향을 줄 수 있는 모듈, 계약, 소유권 경계를 매핑하세요. 가까운 파일 하나만 보고 관계를 추론하지 말고 저장소에서 유지 관리하는 아키텍처 스냅샷을 사용하며, 모듈·의존성·계약이 변경되면 해당 맵을 업데이트하세요. 사양, 계획, 작업, 아키텍처 결정에는 승인된 템플릿을 사용하여 메타데이터, 검증 메모, 교차 링크의 일관성을 유지하세요. ## 사양을 먼저 고치고, 그다음 계획과 작업 목록 고치기 구현 전에 기능 사양을 새로 만들거나 갱신하세요. 요구사항, 비기능 요구사항, 동작 또는 인터페이스 세부사항, 텔레메트리와 정책, 인수 분기를 정의하고, 시각적 동작이 변경될 때는 인터페이스 스케치를 작성하세요. 구현 계획을 생성하기 전에 영향도가 높거나 중간인 모든 질문을 해결하세요. 사양을 업데이트한 뒤 아키텍처적으로 중요한 결과를 아키텍처 결정 기록에 남기고, 해결된 확인 사항은 별도의 기존 확인 목록이 아니라 규범적 섹션에 유지하세요. 그런 다음에만 계획과 작업 체크리스트를 갱신하세요. 테스트를 구현보다 앞에 배치하고, 작업을 90분 이내에 완료할 것으로 예상되는 논리적 증분으로 나누며, 사양·계획·작업이 일치한 뒤 저장소의 분석 게이트를 실행하세요. 사용자가 명시적으로 요청하지 않는 한 폴백이나 호환성 동작을 만들어내지 마세요. ## 저장된 하나의 스냅샷으로 세션을 이어 가고 인계 전에 갱신하기 컨텍스트가 없는 세션을 시작할 때는 저장소의 초기화 또는 인계 런북을 따르세요. 새로운 구현 작업을 시작하기 전에 로드맵 상태, 활성 계획의 진행 상황, 미해결 질문을 요약하세요. 지정된 현재 세션 스냅샷 하나를 세션 간의 실제 상태로 유지하세요. 인계 전에 활성 기능, 완료된 작업, 보류 중인 질문, 검증 상태, 다음으로 안전한 작업을 반영해 업데이트하세요. 서로 경합하는 진행 기록을 만들지 마세요. 기능과 모듈의 소유권을 명시적으로 유지하여 문서, 자동화, 보안, 영속성, 인터페이스 작업이 각각의 기준 위치에서 업데이트되도록 하세요. ## 동작마다 실패하는 테스트를 먼저 쓰기 코드를 변경하기 전에 기준 사양과 계획을 업데이트하세요. 각 동작에 대해 실행 가능한 단위, 동작, 계약 또는 시나리오 테스트를 먼저 작성하거나 확장하고, 의도한 이유로 실패하는지 확인하세요. 계획 중에 성공, 검증, 실패 분기를 나열하고 각 경로에 대한 얇은 실패 테스트를 추가하세요. 테스트를 통과시키는 데 필요한 만큼만 코드를 구현한 다음, 테스트가 계속 통과하는 상태에서 리팩터링하세요. 반복이 끝나면 커버리지 변경, 교훈, 후속 작업을 계획이나 로드맵에 기록하여 판단 과정을 감사할 수 있게 유지하세요. ## 작고 독립된 변경을 하고, 끝난 작업은 바로 완료로 표시하기 각 증분을 자체 완결적으로 유지하고 저장소의 언어, 프레임워크, 문서, 테스트 규칙을 따르세요. 깊게 중첩된 인라인 분기보다 작은 검증 및 정규화 헬퍼로 구성된 직선형 오케스트레이션을 선호하세요. 동작이 변경될 때 로드맵, 사양, 계획, 작업 체크리스트를 동기화하세요. 상태 업데이트를 한꺼번에 처리하지 말고 검증된 각 작업을 즉시 완료로 표시하며, 모듈 관계나 계약이 변경될 때마다 아키텍처 맵을 업데이트하세요. 결정 기록은 확정된 아키텍처 결정에만 사용하세요. 관련 없는 리팩터링, 대규모 포매팅, 추측에 따른 호환성 작업을 피하고 구현을 승인된 증분에 맞게 유지하세요. ## 바뀐 파일 종류에 맞는 검사를 돌리고, 실패는 건너뛰지 말고 조사하기 반복 작업 중에는 적용 가능한 가장 좁은 범위의 포매터, 린터, 정적 분석, 타입 검사, 집중 테스트를 실행하세요. 완료 전에 수정된 파일 유형에 대해 저장소가 요구하는 모든 게이트와 직접 영향을 받는 통합 경계의 게이트를 실행하세요. 실패한 로컬 또는 지속적 통합 검사는 우회할 게이트가 아니라 조사할 결함으로 다루세요. 저장소 정책이 임시 테스트 면제를 명시적으로 허용하는 경우에만 영향을 받는 테스트만 비활성화하고, 명확한 `TODO`와 이유를 추가하며, 후속 작업을 기준 계획에 기록하세요. 변경된 모든 동작에 대해 테스트를 추가하거나 업데이트하세요. 최종 차이를 검토하고, 문서와 테스트 커버리지가 구현과 일치하는지 확인하며, 필수 검사가 실패한 상태에서는 증분을 완료로 선언하지 마세요. ## 의존성 추가나 위험한 Git 작업 전에 승인 받기 증분에 속한 파일만 스테이징 영역에 추가하세요. 생성된 출력, 데이터베이스 산출물, 병렬 작업이 존재할 수 있을 때는 광범위한 스테이징을 사용하지 마세요. 문서와 코드가 함께 변경되는 경우 사양에 미치는 영향을 포함하여 원자적인 관례적 커밋 설명을 준비하되, 실행이 명시적으로 위임되지 않았다면 지정된 운영자가 커밋하도록 두세요. 의존성을 추가하거나 업그레이드하기 전, 정확한 파일이나 디렉터리를 삭제하기 전, 기록을 다시 쓰기 전, 푸시하기 전, 외부 리뷰를 생성하기 전에 명시적인 승인을 받으세요. 승인된 의존성의 근거를 기능 계획에 기록하고 관리형 훅과 품질 파이프라인에 충분한 시간을 허용하세요. 절대 비밀 정보를 커밋하거나 파괴적 정리를 지름길로 사용하지 마세요. 예기치 않은 추적 또는 미추적 파일은 검토할 수 있도록 드러내고 관련 없는 작업은 건드리지 마세요. ## 요청이 없으면 호환용 우회로를 넣지 않고, 위험한 변경은 먼저 제안하기 저장소가 선언한 호환성 방침을 따르세요. 인터페이스를 신규 개발로 취급할 때는 사용자가 현재 작업에서 명시적으로 요청하지 않는 한 폴백, 호환 계층, 레거시 검사를 추가하지 마세요. 프롬프트 요약, 중요한 명령 시퀀스, 근거를 활성 계획이나 연결된 부록에 기록하세요. 위험한 리팩터링, 영속성 변경, 보안 전략 변경, 주요 비기능 트레이드오프는 편집 전에 제안한 다음, 승인된 아키텍처 결정을 적절한 결정 로그에 기록하세요. 자동화된 게이트가 마련될 때까지 향후 계약 테스트, 변이 분석, 보안 훈련을 계획에서 추적하세요. 운영 지침을 그 기준 워크플로 가까이에 두고 문서 전반에 변경 가능한 지침을 중복하지 마세요. ## 테스트는 테스트용 데이터베이스에서만 돌리고, 리셋 전에 연결 대상 확인하기 검증되지 않은 연결을 대상으로 데이터베이스 재설정, 초기화 또는 신규 마이그레이션 명령을 절대 실행하지 마세요. 마이그레이션이나 재설정 전에 활성 환경, 연결 대상, 작업이 폐기 가능한 테스트 데이터베이스로 한정되는지 확인하세요. 애플리케이션 테스트는 저장소의 격리된 테스트 데이터베이스에서 실행하고 문서화된 트랜잭션 또는 마이그레이션 설정을 따르세요. 필요한 경우 명시적으로 식별된 테스트 데이터베이스만 재설정하고, 테스트 명령과 대화형 애플리케이션 명령이 동일한 연결을 공유한다고 가정하지 마세요. 새 마이그레이션을 파일로 만들고 테스트 워크플로를 통해 실행하세요. 데이터베이스 범위가 모호하다면 개발 또는 프로덕션 데이터를 위험에 빠뜨리지 말고 중단한 뒤 확인을 받으세요. ## 단계마다 바뀐 것과 확인한 결과를 인계에 적기 자체 완결적인 증분이 적용 가능한 게이트를 통과한 뒤 완료된 작업, 로드맵 상태, 사양 변경, 결정 기록, 현재 세션 스냅샷이 동기화되었는지 확인하세요. 변경된 파일, 실행한 검사와 결과, 미해결 방해 요소, 후속 작업, 복사해 바로 사용할 수 있는 운영자 명령을 나열하는 간결한 인계를 제공하세요. 구현된 작업과 계획에만 있거나 승인을 기다리는 작업을 구분하세요. 검증 후 기능 커밋을 즉시 준비하되 저장소의 위임 정책 범위 내에서만 실행하세요. 다음 세션이 탐색을 반복하지 않고 재개할 수 있도록 충분한 근거를 보존하세요.