g-ki/agent-skills

작업 구현(Implement Task)

1포인트 티켓 하나를 리뷰용 PR로 전달합니다. 티켓이 요청한 내용만 정확히 포함하고 그 이상은 포함하지 않습니다.

입력(Input)

$ARGUMENTS

• 티켓(Ticket), 필수: 트래커 키(예: ENG-123) 또는 로컬 ID(예: T-04). 누락된 경우 준비된 티켓(상태가 open이고 의존성이 병합된)을 중요 경로 순서대로 나열하고 어떤 것을 진행할지 물어보세요. 무인 모드에서는 대신 blocked를 보고하세요.
• --tasks <file>: 로컬 작업 파일. 지정되지 않은 경우, 프로젝트의 로컬 git-ignored RFC 폴더(예: .rfcs/)에서 해당 티켓이 포함된 *.tasks.md 파일을 찾은 후 docs/rfcs/에서 찾으세요.
• --base <branch>: 시작하고 PR의 대상이 될 브랜치. 기본값은 main입니다. main이 아닌 베이스는 PR이 다른 티켓의 병합되지 않은 PR 위에 **스택(stacked)**되었음을 의미합니다.
• --branch <name>: 사용할 브랜치 이름. 그렇지 않으면 1단계의 명명 규칙을 따르세요.
• --feedback <pr>: 구현하지 말고 기존 PR의 리뷰 피드백을 처리하세요(마지막 섹션 참조).
• --unattended: 오케스트레이터에 의해 시작되었으며 누구도 질문에 답할 수 없습니다. 절대 묻지 말고, 질문해야 할 상황이면 중단하고 보고서에 설명하세요. 자신의 워크트리(worktree)에서 작업을 수행하세요.

티켓 및 로컬 파일 위치(Where the ticket and local files live)

• 트래커 우선. 티켓에 트래커 키(인수로 제공되거나 작업 파일의 Tracker: 필드에 있음)가 있는 경우 연결된 트래커 도구(Linear, Jira, GitHub Issues 등)를 통해 가져오세요. 게시된 경우 트래커가 티켓 내용의 진실 공급원(source of truth)입니다. 취소되었거나 완료된 경우 중단하고 보고하세요.
• 그 외에는 로컬 작업 파일 및 트래커 이슈에 없는 필드(파일, 범위 외)에 사용합니다. RFC 및 작업 파일은 개발자의 로컬 추적되지 않는 문서이므로 메인 프로젝트 폴더에만 존재하며 워크트리에는 없습니다. 워크트리 내에 있는 경우 git worktree list(첫 번째 항목)를 사용하여 메인 폴더를 찾고 절대 경로로 해당 파일을 읽으세요. 메인 폴더를 읽기 전용으로 취급하세요. 절대 편집하거나 체크아웃하거나 git 명령을 실행하지 마세요.
• 절대 RFC, 노트 또는 작업 파일을 커밋하지 마세요. git add -A가 아닌 명시적 경로로 파일을 스테이징하세요.

1. 티켓 선택(Pick the ticket)

• 인수 기준 및 의존성을 포함하여 티켓(위 참조)을 읽으세요. 유형이 spike인 경우 중단하세요. 스파이크는 결정을 생성하지만 PR은 생성하지 않습니다. /spike-task를 가리키세요(무인 모드: blocked 보고).
• 의존성은 해당 PR이 main에 병합되거나(gh로 PR 상태 확인 또는 의존성 상태 pr-merged/done 확인), 또는 베이스 브랜치가 해당 의존성의 자체 브랜치(스태킹)인 경우 충족됩니다. 스파이크 의존성은 done 상태(결정이 승인되고 백로그가 정제됨)인 경우에만 충족됩니다. 충족되지 않은 의존성이 있으면 중단하고 어떤 것인지 말하세요.
• 작업 트리가 깨끗한지 확인하고, 가져온 후(fetch) 최신 origin/<base>에서 브랜치를 생성하세요.
• 브랜치 이름(--branch가 제공되지 않은 경우): <username>/<project-slug>/<task-branch>.
  • username: 사용자의 기존 브랜치가 이 패턴을 따르는 경우 해당 접두사, 그렇지 않으면 GitHub 로그인(gh api user --jq .login).
  • project-slug: 작업 파일의 Project slug: 헤더에서 가져오거나, RFC 이름을 케밥 케이스로 변환한 값.
  • task-branch: 트래커 키와 짧은 슬러그의 조합(예: eng-123-add-v2-flag 키는 트래커 통합이 PR을 연결할 수 있게 함), 또는 게시되지 않은 경우 t-04-add-v2-flag.
• 사용자와 직접 작업하는 경우(무인 모드가 아님) 작업 파일에서 티켓 상태를 in progress로 설정하고, GitHub 통합이 자동으로 처리하지 않는 경우 트래커에서도 설정하세요.

2. 티켓에 필요한 것만 로드(Load only what the ticket needs)

티켓, 티켓이 의존하는 RFC 섹션, 그리고 티켓이 명명한 파일을 읽으세요. 그런 다음 실제 흐름을 추적하세요. 호출자, 기존 헬퍼, 변경할 코드 옆에 있는 테스트를 확인하세요. 문제를 완전히 이해할 수 있을 만큼 읽되, 전체 RFC 또는 세션 기록을 로드하지 마세요. 티켓은 독립적으로 작동하도록 작성되었습니다. 그렇지 않은 경우 추측하지 말고 보고해야 할 간격(gap)입니다.

3. 먼저 테스트 작성(Write the tests first)

각 인수 기준을 저장소의 기존 테스트 프레임워크, 위치 및 스타일을 사용하여 테스트로 전환하세요. 테스트를 실행하고 올바른 이유로 실패하는지 확인하세요. 기준당 하나의 집중된 테스트면 충분합니다. 기존 패턴에서 요구하지 않는 한 새 테스트 유틸리티, 픽스처 또는 헬퍼는 필요하지 않습니다. 순수하게 기계적인 티켓(예: 플래그 추가)은 기준이 기존 테스트나 타입 검사기로 확인되는 경우 새 테스트가 필요하지 않을 수 있습니다. PR에서 그렇게 말하세요.

4. 가장 작은 완전한 변경 구현(Implement the smallest complete change)

"완전한"은 모든 인수 기준이 통과함을 의미합니다. "가장 작은"은 그 이상을 의미하지 않습니다. 이는 포니테일(ponytail) 접근 방식을 따릅니다. ponytail 스킬이 설치된 경우 지금 기본 수준으로 로드하고 이 단계를 관리하도록 하세요.

그렇지 않으면 작동하는 첫 번째 옵션을 선택하세요:

1. 이미 요구 사항이 충족되었는가? 기존 코드가 이미 기준을 충족하면 중단하고 티켓 종료를 제안하세요.
2. 코드베이스에 이미 있는 것(헬퍼, 타입, 패턴)을 재사용하세요.
3. 표준 라이브러리, 그 다음 네이티브 플랫폼 기능(DB 제약 조건, 내장 HTML 입력, JS보다 CSS), 그 다음 이미 설치된 의존성을 사용하세요.
4. 그때서야 새 코드를 가능한 한 적게 작성하세요.

작성하는 동안:

• 추측성 구조 금지. 하나의 구현만 있는 인터페이스, 하나의 제품만 위한 팩토리, 절대 변경되지 않는 값에 대한 설정, "나중을 위한" 스캐폴딩은 금지합니다. 새 파일을 만드는 것보다 기존 파일을 편집하는 것을 선호하세요.
• 주변 코드와 일치: 명명, 오류 처리, 구조. diff는 코드베이스가 작성한 것처럼 보여야 합니다.
• 코드가 말할 수 없는 경우에만 주석. 코드가 무엇을 하는지 설명하거나, 티켓을 다시 설명하거나, 주석 처리된 코드나 디버그 출력을 남기지 마세요. 추가할 가치가 있는 유일한 주석은 의도적인 단순화에 대한 것입니다: 한계를 명명하고 언제 업그레이드할지 명시하여 누군가 실수로 "수정"하는 것을 방지하세요.
• 버그는 근원에서 수정. 공유 함수를 변경하기 전에 모든 호출자를 확인하세요.
• 안전 최소화 금지. 신뢰 경계에서의 입력 유효성 검사, 데이터 손실을 방지하는 오류 처리, 보안 및 접근성 기본 사항은 티켓에 명시되지 않더라도 항상 적절히 수행되어야 합니다.

5. 범위 보호(Guard the scope)

티켓이 1포인트보다 큰 경우(약 하루 이상, 두 번째 관심사가 나타나거나, 관련 없는 영역을 건드리지 않고는 기준을 충족할 수 없는 경우) 중단하세요. 깨끗한 것 외에는 아무것도 커밋하지 말고, 발견한 내용을 설명하고, 승인을 위해 새 티켓으로 분할을 제안하세요. 사용자와 작업하는 경우 작업 파일에 작성하고, 무인 모드인 경우 보고서에 작성하세요. 발견한 관련 없는 문제는 diff가 아닌 PR 노트에 넣으세요. 통과시키기 위해 인수 기준을 약화시키거나 재해석하지 마세요.

6. 검증 및 PR 개설(Verify and open the PR)

1. 저장소가 하는 방식대로 테스트, 린터, 타입 검사기를 실행하세요. 변경 사항에 런타임 동작이 있고 /verify를 실행할 수 있으면 실행하고, 그렇지 않으면 프로젝트 자체의 실행 또는 확인 명령을 사용하여 동작을 실행하세요.
2. 전체 diff를 직접 다시 읽으세요. 모든 변경된 줄은 인수 기준으로 추적 가능해야 합니다. 관련 없는 서식, 이름 변경, 잘못된 파일을 제거하고 로컬 RFC나 작업 파일이 포함되지 않았는지 확인하세요.
3. 저장소의 커밋 스타일을 따라 커밋하고, 푸시한 후 베이스 브랜치를 대상으로 templates/pr.md를 사용하여 리뷰 준비 완료 상태(초안이 아님. 리뷰 자동화가 실행되도록. 사용자가 초안을 요청하지 않은 경우)로 PR을 개설하세요. 제목에 트래커 키를 넣고 설명에 트래커 이슈를 링크하세요. 베이스가 main이 아닌 경우 어떤 PR 위에 스택되었는지와 해당 PR이 먼저 병합되어야 한다고 명시하세요. 여기서 PR을 개설할 수 없으면 브랜치를 푸시하고 응답에 PR 텍스트를 포함하세요.
4. 사용자와 직접 작업하는 경우 티켓 상태를 pr-open(또는 pr-draft)으로 설정하고 작업 파일에 Branch / PR:을 채우고, GitHub 통합이 자동으로 처리하지 않는 경우 트래커 이슈를 리뷰 상태로 이동하세요. 무인 모드에서는 상태를 오케스트레이터에 맡기세요.
5. 아래 보고서로 마무리하세요. 사용자가 있는 경우 2-3줄 버전으로 충분합니다.

PR 피드백 처리(Addressing PR feedback) (--feedback)

PR과 처리할 리뷰 항목 목록(코멘트 링크 및 수행할 작업)을 받습니다.

1. 워크트리에서 PR의 브랜치를 가져와 체크아웃하세요. 티켓과 항목을 읽고 현재 diff를 읽으세요.
2. 4단계와 동일한 규칙에 따라 각 항목을 해결하는 가장 작은 변경으로 처리하세요. 티켓 범위 내에 유지하세요. 항목이 범위를 벗어난 것을 요구하면 구축하지 말고 후속 작업으로 보고하세요.
3. 수정하거나 force-push하지 말고 새 커밋을 추가하여 리뷰어가 리뷰 이후 무엇이 변경되었는지 볼 수 있게 하세요. 테스트를 실행한 다음 푸시하세요.
4. 처리된 각 코멘트 스레드에 변경된 내용과 짧은 커밋 SHA를 한 줄로 답변하세요. 코드 변경 없이 답변하라고 지시받은 항목의 경우 주어진 텍스트로 답변하세요. 항목을 변경해서는 안 된다고 결론 내린 경우 스레드에서 논쟁하지 말고 남겨두고 보고서에 설명하세요.
5. 모든 항목이 처리된 경우 done, 그렇지 않은 경우 blocked를 사용하여 보고서로 마무리하세요.

보고서(Report)

오케스트레이터가 파싱할 수 있도록 최종 메시지를 다음 블록으로 정확히 끝내세요:

RESULT: done | blocked | needs-split | already-met
TICKET: <local id> / <tracker key or "unpublished">
PR: <url or "none">
BRANCH: <branch or "none">
SKIPPED: <deliberate limits or items not addressed, or "none">
NOTES: <one or two lines: why blocked, what to split, follow-ups, unrelated issues found>