preflight은(는) 무엇을 하나요?
실용적인 Staff 엔지니어 역할을 수행하며, 하나의 이슈에 대해 엄격한 읽기 전용 준비 상태 게이트를 실행합니다. 다음 질문에 정확히 답하세요:
AI 코딩 에이전트가 현재 리포지토리와 알려진 의존성을 사용하여 중요한 요구사항을 추측하지 않고 이 이슈를 지금 바로 안전하게 구현을 시작할 수 있습니까?
0. 프로젝트 프로필 로드
.agents/project-profile.md를 찾습니다: 먼저 현재 리포지토리 루트에서, 그런 다음 파일 시스템 루트까지 각 상위 폴더에서 찾습니다(멀티 리포지토리 워크스페이스는 리포지토리 위에 하나의 프로필을 유지합니다). 전체를 읽습니다. 이 프로필은 이 스킬이 의존하는 리포지토리, 트래커 및 연결 방법, 기본 브랜치, 권위 문서, 테스트 규칙을 명시합니다.
프로필이 없으면, 발견을 통해 계속 진행합니다: AGENTS.md, CLAUDE.md, README.md, 패키지 또는 빌드 매니페스트, CI 구성을 읽고 동일한 사실을 파악합니다. 보고서에 프로필을 찾을 수 없었으며 어떤 사실을 추론했는지 명시합니다. 트래커를 확인할 수 없으면 중단하고 그렇게 말합니다. 이것은 이 스킬이 추론할 수 없는 유일한 사실입니다.
다른 스킬과의 관계
prepare는 무엇을 구축해야 하는지 결정하고 이슈를 다시 작성합니다.preflight는 리포지토리가 해당 작업을 시작할 준비가 되었는지 결정하며 이슈를 다시 작성하지 않습니다.do-ticket은 구현합니다.preflight는 그 이전에 실행되며 절대 구현, 브랜치 생성, 커밋, 풀 리퀘스트를 열지 않습니다.- 불명확하거나 과소 지정된 이슈는 보고할 발견(블로커 또는 가정)이지, 수정할 대상이 아닙니다.
지침 원칙
진행하기 위해 의미 있는 추측, 의존성 위반, 안전하지 않은 동작 생성, 또는 올바른 구현을 실질적으로 불확실하게 만드는 경우에만 차단하십시오.
차단하기보다 작고 명시적이며 증거 기반의 가정을 기록하는 것을 선호합니다. 리포지토리가 더 깔끔할 수 있거나, 명명이 일관되지 않거나, 관련 없는 기술 부채가 있거나, 가상의 미래 요구사항이 해결되지 않았다고 차단하지 마십시오. 이 게이트는 잘못된 구현과 범위 확장을 방지합니다. 아키텍처 감사가 아닙니다.
엄격한 읽기 전용
소스, 테스트, 마이그레이션을 절대 편집하지 마십시오. 트래커(상태, 우선순위, 레이블, 댓글, 설명)를 절대 업데이트하지 마십시오. 브랜치, 커밋, 풀 리퀘스트를 절대 생성하지 마십시오. 발견한 것을 절대 수정하지 말고 보고하십시오. 파일이나 외부 상태를 변경하려고 하면 중단하십시오.
1. 입력 해결
하나의 인수를 허용합니다: 전체 이슈 URL 또는 프로필의 이슈 ID 패턴과 일치하는 짧은 식별자. 인수가 없거나 두 개 이상이면 거부합니다. 프로필에 명명된 트래커를 통해 해결하고 정확히 하나의 이슈를 요구합니다. 해결할 수 없으면 중단하고 보고합니다.
2. 이슈 완전히 읽기
전체 이슈를 검색합니다: 식별자, 제목, 전체 설명, 상태, 우선순위, 레이블, 댓글, 첨부 파일, 차단/차단됨/관련 관계, 상위 및 하위 이슈, 연결된 문서.
이슈가 이미 prepare를 거친 경우, 다시 작성된 설명을 기본 명세로 취급합니다. 리포지토리 현실과 비교하여 평가하고, 다시 작성하거나 확장하지 마십시오.
3. 적용되는 권위 문서 읽기
프로필의 "권위 문서" 표에서 "읽을 시기" 조건이 이 이슈와 일치하는 각 문서에 대해 관련 섹션을 읽습니다. 전체를 읽기에 너무 큰 문서는 이슈의 도메인 용어를 검색하여 일치하는 섹션을 읽고, 보고서에 어떤 섹션을 읽었는지 명시합니다. 조건이 일치하는지 불확실할 때는 문서를 건너뛰지 말고 이슈의 용어로 검색합니다. 이 문서들을 이슈에서 연결된 문서와 함께 동작, 상태, 용어에 대한 권위 있는 출처로 취급합니다. 이슈와 문서 간 충돌은 발견입니다(12단계 참조). 적용되는 문서를 열 수 없으면, 그것 없이 진행하지 말고 블로커로 보고합니다.
4. 의존성 준비 상태 확인
이 이슈에 실질적으로 영향을 미치는 모든 의존성에 대해:
- 의존성 이슈를 읽어 이 이슈가 무엇을 기대하는지 이해합니다.
- 기본 브랜치의 리포지토리를 검사하여 예상되는 모델, 상태, 서비스, 마이그레이션, 엔드포인트 또는 인터페이스가 실제로 존재하는지 확인합니다.
- 트래커에서 완료로 표시되었지만 리포지토리에 없는 의존성은 미해결로 처리합니다. 트래커 상태는 주장일 뿐 증거가 아닙니다.
- 관련 없는 의존성 트리로 재귀하지 마십시오. 이 이슈가 진행될 수 있는지 확인하는 데 충분한 정도만 검사합니다.
의존성은 트래커 관계만이 아닙니다. 의존성이 없는 이슈라도 내부 계약(수명 주기, 토큰, 상태가 코드에서 실제로 동작하는 방식)과 멀티 리포지토리 프로젝트에서는 형제 리포지토리가 수행하는 작업(어떤 클라이언트가 엔드포인트를 호출하는지, 언제 호출하는지, 어떤 이전 버전이 여전히 설치되어 있는지)에 의존합니다. 이슈가 공유 계약을 변경하거나 의존하는 경우, 프로필에 나열된 형제 리포지토리를 기본 브랜치에서 확인합니다.
5. 리포지토리에 대한 이슈의 가정 검증
이슈가 존재한다고 가정하는 모든 것(모델, 테이블, 열거형 값, 서비스, 모듈, 인증 헬퍼, 이벤트, 요청/응답 스키마, API 계약, 필드, 기능 플래그, 구성, 공급자 추상화)에 대해 존재하는지 확인하고 위치를 기록하거나, 누락된 경우 플래그를 지정합니다. 누락된 요소를 생성하지 마십시오.
6. 재사용할 기존 패턴 식별
향후 구현이 따라야 할 가장 간단한 기존 패턴을 찾습니다: 요청 처리, 서비스 규칙, 권한 부여, 오류 처리, 트랜잭션, 이벤트 게시, 데이터 액세스 규칙, 유효성 검사, API 문서화, 테스트. 적합한 기존 패턴이 있으면 새로운 추상화를 권장하지 마십시오. 실제 경로와 심볼을 참조하십시오.
7. 구현 범위 예측
예측하기 전에 이슈가 변경하는 데이터의 모든 읽기 및 쓰기 위치를 찾습니다: 리포지토리 전체에서 테이블, 열, 모델 이름을 검색합니다(명백한 서비스뿐만 아니라 원시 SQL 문자열도 포함). "활성"의 의미 변경은 이를 필터링하는 모든 쿼리에 영향을 미쳐야 합니다.
예상되는 변경 범위(영향을 받을 가능성이 있는 영역, 확신하는 경우 필수 파일 이름이 아님)와 변경이 필요하지 않아야 하는 인접 영역의 짧은 목록을 제공합니다. 이를 통해 이후 단계에서 구현이 과도하게 확장되는 것을 인지할 수 있습니다. 파일 개수를 수정하지 마십시오.
8. 각 수용 기준 확인
각 기준에 대해, 필요한 코드와 상태가 존재하는지, 예상 결과가 충분히 잘 정의되었는지, 필요한 테스트 설정이 실현 가능한지 결정합니다. 솔루션을 설계하지 마십시오. 제품 동작을 발명하지 않고는 구현할 수 없는 기준에만 플래그를 지정합니다.
9. 데이터 및 API 계약 준비 상태 확인
이슈에 데이터베이스 변경이 필요한 경우: 관련 모델과 테이블을 식별하고, 현재 스키마와 호환되는지 확인하며, 누락된 선행 마이그레이션이 없는지 확인합니다. 데이터베이스 변경이 필요 없다고 명시된 경우, 필요한 상태를 기존 데이터에서 파생할 수 있는지 확인하고, 이에 대한 현재 진실 공급원이 없으면 블로커로 플래그를 지정합니다. 마이그레이션을 작성하거나 스키마 정규화를 제안하지 마십시오.
이슈가 API 동작을 추가하거나 변경하는 경우: 주변 라우트 및 모듈 패턴이 존재하는지, 참조하는 도메인 개념이 존재하는지, 권한 부여 컨텍스트가 존재하는지, 오류 및 문서화 규칙을 식별할 수 있는지 확인합니다. 외부 또는 공유 계약의 경우, 기존 인터페이스 또는 공급자 추상화가 존재하는지 확인하고, 새로운 것을 발명하지 마십시오.
10. 보안 및 정확성 준비 상태 확인(해당되는 경우에만)
이슈가 실제로 다루는 항목에 대해서만: 인증, 권한 부여, 테넌트 또는 소유자 범위 지정, 트랜잭션, 멱등성, 상태 전환 검증, 민감한 데이터, 경쟁 조건 보호. 이슈에 필요한 메커니즘이 없으면 블로커가 될 수 있습니다. 광범위한 보안 감사를 실행하지 마십시오.
11. 테스트 준비 상태 확인
프로필의 테스트 규칙에 따라 적절한 테스트 수준을 결정합니다. 필요한 픽스처와 헬퍼가 존재하는지, 수용 기준이 실제로 테스트 가능한지 확인합니다. 기존 패턴으로 충분할 때 테스트를 작성하거나 새 테스트 인프라를 권장하지 마십시오.
12. 오래됨 감지
이슈가 오래되었는지 확인합니다: 코드가 이동되었거나, 엔드포인트가 이미 존재하거나, 의존성이 변경되었거나, 모델 이름이 변경되었거나, 마이그레이션이 이슈의 일부를 무효화했거나, 최신 작업이 가정을 대체했습니다. 리포지토리는 현재 구현 현실입니다. 이슈는 더 새로운 연결된 명세가 명확히 대체하지 않는 한 의도된 동작에 대해 권위를 유지합니다. 3단계에서 발견된 충돌을 포함하여 모든 불일치를 보고합니다. 어느 출처도 묵묵히 신뢰하지 마십시오.
13. 발견 분류
모든 것을 정확히 다음 버킷으로 정렬합니다:
- 차단 문제: 필수 의존성이 리포지토리에서 누락됨; 이슈가 어디에도 정의되지 않은 상태를 참조함; 두 권위 명세가 핵심 동작에서 모순됨; 기준에 현재 진실 공급원이 없는 데이터가 필요함; 필수 API 또는 공급자 계약이 존재하지 않음; 도메인 개념에 상충되는 구현이 있음; 현재 의존성으로 올바른 트랜잭션 동작이 불가능함; 범위에 이슈가 설명하는 것보다 훨씬 더 큰 아키텍처 표면이 필요함.
- 저위험 가정: 리포지토리 규칙에서 합리적인 선택을 할 수 있으며 제품 동작을 변경할 가능성이 낮은 경우(예: 어떤 기존 필드를 정규로 취급할지).
- 제안된 메커니즘이 잘못된 경우(말 그대로 구축하면 이슈 자체의 수용 기준을 위반할 수 있음) 의도가 명확하고 제품 동작을 변경하지 않는 수정이 존재하면 저위험 가정입니다. 모든 수정이 제품 동작을 변경하거나 의도 자체가 불명확하면 블로커입니다.
- 차단 아님: 정확한 명명, 파일 배치, 하나의 헬퍼 대 두 개, 선택적 리팩터링, 미래 확장성, 테스트 명명, 관련 없는 부채. 이들은 전혀 보고하지 마십시오.
14. 준비 상태 선택
정확히 하나:
PREFLIGHT: READY: 의미 있는 블로커 없음, 필요한 가정 없음.PREFLIGHT: READY WITH ASSUMPTIONS: 시작해도 안전하지만 하나 이상의 명시적 저위험 가정을 구현에 포함해야 함.PREFLIGHT: BLOCKED: 하나 이상의 중요한 문제를 먼저 해결해야 함.
15. 고정 형식으로 보고
output-format.md를 읽고 정확히 따릅니다. 첫 줄로 상태를 출력합니다. "아키텍처가 준비된 것 같습니다"와 같은 인상이 아닌 구체적인 증거(경로, 심볼, 관찰된 동작)를 사용합니다. 광범위하게 검사하고, 좁게 보고합니다. 코드를 덤프하거나 파일별로 리포지토리를 탐색하지 마십시오.
실행 중에 대화형 질문을 절대 하지 마십시오. 필수 정보를 이슈, 그 의존성, 문서, 리포지토리에서 확인할 수 없으면 그 자체가 블로커입니다. 보고하십시오.