agentleFS
develeepdeveleep/dev-gongbang/skills/in-progress/set-ticket/SKILL.md

set-ticket

Skill1 starsChanged 19 days agoMITView on GitHub

set-brief로 남긴 이슈나 docs/context/ 문서가 한 번에 작업하기에 클 때, 혼자 검증할 수 있는 작은 티켓으로 나눠 GitHub sub-issue나 docs 파일로 남기고 원래 brief에 티켓 목록을 연결한다.

The file

Files
SKILL.md

Set Ticket

set-brief 기록 하나를 티켓 여러 개로 나눈다. 티켓을 읽는 사람은 대화도 brief 작성 과정도 보지 못한 작업자나 다른 에이전트다. 티켓 하나만 읽고 그 티켓의 작업을 끝낼 수 있어야 한다.

핵심 규칙

  1. 티켓마다 수직 슬라이스로 자른다. 한 계층만 다루지 않고 필요한 모든 계층(스키마, API, UI, 테스트)을 좁게 관통한다. 끝낸 티켓은 혼자서 시연하거나 검증할 수 있어야 한다.
  2. 티켓 하나는 새 컨텍스트 창 하나로 끝낼 수 있는 크기로 만든다. 작업자가 이전 티켓의 대화 없이 시작하기 때문이다.
  3. "만들 것"에는 구현할 파일 경로와 코드를 적지 않고 동작으로 적는다. 구현 경로와 코드는 빨리 낡는다. 바뀌는 이름(필드, 타입, 열, 함수)과, 완료 기준을 확인할 명령과 기대 결과는 적는다. run-ticket은 완료 기준을 명령이나 관찰로 하나씩 확인한다. 프로토타입이 만든 코드가 결정(상태 기계, 스키마, 타입 형태)을 글보다 정확히 담으면 결정이 담긴 부분만 넣고 프로토타입에서 왔다고 적는다. 다른 티켓의 결과는 경로 대신 "NN 티켓의 산출물"로 가리킨다(3단계 "산출물").
  4. brief의 제한요소를 티켓으로 옮긴다. "하면 안 되는 것", "바꾸지 않는 범위", "바꿀 수 없는 조건" 중 그 티켓과 관련된 항목을 옮긴다. 관련 여부가 애매하면 옮긴다. 제한요소는 brief 문구를 그대로 쓴다.
  5. brief는 닫지 않고, "티켓" 섹션을 덧붙이는 것 외에는 고치지 않는다. 티켓은 brief 문구를 옮겨 쓰고 부모로 brief를 가리키므로, brief를 고치면 티켓과 어긋나고 닫으면 작업자가 전체 맥락을 찾지 못한다.

주의할 점

  • 티켓에는 대화 맥락이 없으면 판단할 수 없는 설명과 미사여구를 쓰지 않는다. "앞서 정한 방식대로", "위 티켓처럼", "깔끔하게" 대신 이름, 값, 티켓 번호를 직접 적는다.

단계

아래 체크리스트를 시작할 때 한 번 보여 주고, 단계를 마칠 때마다 갱신한다.

티켓 진행:
- [ ] 1. brief 찾기
- [ ] 2. 코드베이스 탐색
- [ ] 3. 분할안 작성
- [ ] 4. 분할안 확인
- [ ] 5. 게시와 brief 연결

1. brief 찾기

  • 인자가 이슈 번호나 URL이면 gh issue view <번호> --comments로 본문과 코멘트를 끝까지 읽는다.
  • 인자가 경로면 그 문서를 끝까지 읽는다.
  • 인자가 없으면 다음 순서로 찾는다.

    1. 이 대화가 set-brief 게시로 끝났으면 그때 만든 이슈나 문서
    2. gh issue list --label context --json number,title,createdAt,body의 이슈 중 가장 최근 것과, - 작성일: 줄이 있는 문서 중 작성일이 가장 늦은 것을 비교해 더 최근 것. 본문에 ## 티켓 섹션이 이미 있거나 "남은 일"에 빈 체크박스가 없는 brief는 이미 나눴거나 끝난 것이므로 건너뛴다. 문서는 command grep -rlE --include='*.md' --exclude-dir=.git --exclude-dir=node_modules '^- 작성일: [0-9]{4}-[0-9]{2}-[0-9]{2}' .로 찾는다. brief가 docs/context/ 밖에 저장됐을 수 있고, Grep 도구와 셸 함수(ugrep 등)로 바뀐 Bash grep은 .gitignore에 걸린 폴더를 건너뛰므로 command grep으로 찾는다.

    찾은 brief로 바로 진행하고, 어떤 brief를 골랐는지 한 줄로 알린다. 하나도 없으면 그렇다고 알리고 멈춘다.

2. 코드베이스 탐색

이 대화에서 아직 코드를 보지 않았으면 brief가 다루는 영역의 현재 상태를 파악한다. 저장소에 용어집이나 ADR이 있으면 티켓 제목과 설명에 그 용어를 쓰고 ADR을 따른다. 구현을 쉽게 만드는 선행 리팩터링(prefactoring)을 찾는다.

3. 분할안 작성

핵심 규칙 1~2로 brief의 "남은 일"을 티켓으로 나눈다. 선행 리팩터링이 있으면 첫 티켓으로 둔다.

티켓마다 완료 기준을 정한다. brief "확인 기준" 중 그 티켓만 끝나도 확인할 수 있는 항목은 문구를 그대로 옮긴다. 나머지는 run-ticket이 마지막 티켓을 끝낼 때 brief에서 실행한다.

티켓마다 막힘 관계를 정한다. 그 티켓을 시작하기 전에 끝나야 하는 다른 티켓이다. 막는 티켓이 없으면 바로 시작할 수 있다.

산출물: 한 티켓의 결과(예: 수정 전 동작 체크리스트, 측정값)를 다른 티켓이 쓰면, 만드는 티켓의 "만들 것"에 "결과를 이 티켓의 산출물로 남긴다"를, 쓰는 티켓의 완료 기준에 "NN 티켓의 산출물"을 적고 쓰는 티켓을 만드는 티켓에 막히게 한다. 티켓마다 새 세션에서 실행되므로 이렇게 적지 않으면 뒤 티켓이 결과를 찾지 못한다. 실행 스킬(run-ticket)은 산출물을 docs 티켓의 ## 산출물 섹션이나 GitHub 티켓의 완료 코멘트에 남긴다.

넓은 리팩터링은 수직 슬라이스의 예외다. 열 이름 변경이나 공유 타입 변경처럼 기계적인 변경 하나가 코드 전체로 퍼져서 어떤 슬라이스도 혼자 초록 상태로 들어갈 수 없으면, expand–contract 순서로 나눈다.

  1. expand: 옛 형태 옆에 새 형태를 추가해 아무것도 깨지지 않게 한다.
  2. migrate: 호출부를 패키지나 디렉터리 단위로 묶어 옮긴다. 묶음마다 티켓 하나이고, 모두 expand에 막힌다. 옛 형태가 남아 있으므로 묶음마다 CI가 초록이다.
  3. contract: 호출부가 남지 않으면 옛 형태를 지운다. 모든 migrate 티켓에 막힌다.

묶음끼리도 혼자 초록이 될 수 없으면 순서는 유지하고, 묶음들이 통합 브랜치 하나를 공유하게 한 뒤 마지막 "통합 및 검증" 티켓을 모두가 막게 한다. 초록은 그 티켓에서만 약속한다.

4. 분할안 확인

분할안을 번호 목록으로 보여 준다. 티켓마다 다음을 적는다.

  • 제목
  • 막힘 관계: 먼저 끝나야 하는 티켓 번호, 없으면 "없음"
  • 만들 것: 이 티켓이 동작하게 만드는 끝에서 끝까지의 동작
  • 완료 기준: 외부에서 관찰할 수 있는 기준. 명령이면 기대 결과까지

그리고 묻는다.

  • 단위 크기가 맞나요? (너무 큼 / 너무 작음)
  • 막힘 관계가 맞나요? 각 티켓이 정말 그 티켓을 막는 티켓에만 의존하나요?
  • 합치거나 더 나눌 티켓이 있나요?

사용자가 승인할 때까지 고쳐서 다시 보여 준다.

5. 게시와 brief 연결

brief가 있는 곳에 게시한다. 막는 티켓을 먼저 만들어야 막힘 관계에 실제 번호를 쓸 수 있으므로, 막힘 관계 순서대로 만든다.

GitHub 이슈

  1. gh label list --search ready-for-agent에 ready-for-agent가 없으면 gh label create ready-for-agent로 만든다.
  2. 티켓마다:
    1. "이슈 티켓 템플릿"으로 쓴 본문을 임시 파일에 저장하고 gh issue create --title "<제목>" --body-file <임시 파일> --label ready-for-agent로 만든다.
    2. brief의 sub-issue로 연결한다. gh api --method POST repos/{owner}/{repo}/issues/<brief 번호>/sub_issues -F sub_issue_id=<티켓 database id>. database id는 gh api repos/{owner}/{repo}/issues/<번호> --jq .id로 얻는다. #번호나 node_id가 아니다. 실패하면 티켓 본문 맨 위에 Part of #<brief 번호>를 넣는다.
    3. 막는 티켓마다 gh api --method POST repos/{owner}/{repo}/issues/<티켓 번호>/dependencies/blocked_by -F issue_id=<막는 티켓 database id>로 연결한다. 실패하면 티켓 본문에 "막힘 관계" 섹션을 넣는다.
  3. brief 본문 끝에 "티켓" 섹션을 덧붙인다. gh issue view <brief 번호> --json body --jq .body로 본문을 임시 파일에 받고, 아래 형식을 덧붙여 gh issue edit <brief 번호> --body-file <임시 파일>로 올린다.
    ## 티켓
    - [ ] #<번호> <제목>
    막힘 관계 순서로 적는다.
  4. 티켓 URL 목록을 알리고 임시 파일을 지운다.

docs 문서

  1. brief와 같은 디렉터리에, brief 파일 이름에서 .md를 뺀 폴더를 만든다. 예: docs/context/YYYY-MM-DD-<brief-slug>/. 레포 규칙이 정한 티켓 폴더 이름(issues/ 등)은 쓰지 않는다.
  2. 티켓 하나당 파일 하나를 NN-<slug>.md로 저장한다. NN은 01부터 막힘 관계 순서로 매긴다. slug는 제목을 영문 소문자와 하이픈으로 줄인 것이다. 같은 이름의 파일이 있으면 덮어쓰기 전에 묻는다.
  3. brief 문서 끝에 "티켓" 섹션을 덧붙인다.
    ## 티켓
    - [ ] [NN: <제목>](./YYYY-MM-DD-<brief-slug>/NN-<slug>.md)
  4. 저장하고 고친 파일 목록을 알린다. 커밋은 하지 않는다.

실행 안내

게시를 마친 뒤 새 세션에서 /run-ticket으로 티켓을 하나씩 실행하라고 안내한다. run-ticket은 User-invoked라 이 스킬에서 호출할 수 없다.

이슈 티켓 템플릿

내용이 없는 섹션은 지운다.

## 부모
- #<brief 번호>

## 만들 것
<이 티켓이 동작하게 만드는 끝에서 끝까지의 동작. 사용자가 관찰하는 관점으로 쓰고, 계층별 구현 목록으로 쓰지 않는다>

## 완료 기준
- [ ] <외부에서 관찰할 수 있는 기준>

## 막힘 관계
- #<번호> (네이티브 연결에 실패했을 때만 둔다)

## 하면 안 되는 것
- <brief에서 옮긴 항목>

## 작업 경계
- 바꾸지 않는 범위: <brief에서 옮긴 항목>
- 바꿀 수 없는 조건: <brief에서 옮긴 항목>

docs 티켓 템플릿

내용이 없는 섹션은 지운다. 상태는 ready-for-agent로 만들고, run-ticket이 끝내면 done으로 바꾸고 ## 완료 기록을 붙인다. GitHub 티켓은 닫히면 끝난 것이다.

# NN: <제목>

- 부모: [<brief 제목>](../YYYY-MM-DD-<brief-slug>.md)
- 막힘 관계: <NN: 제목>, 없으면 "없음 (바로 시작 가능)"
- 상태: ready-for-agent

## 만들 것
<이 티켓이 동작하게 만드는 끝에서 끝까지의 동작>

## 완료 기준
- [ ] <외부에서 관찰할 수 있는 기준>

## 하면 안 되는 것
- <brief에서 옮긴 항목>

## 작업 경계
- 바꾸지 않는 범위: <brief에서 옮긴 항목>
- 바꿀 수 없는 조건: <brief에서 옮긴 항목>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.