pedro-oscar/shorts-ai

Matt에게 물어보세요

모든 스킬을 기억할 필요는 없습니다. 그러니 물어보세요.

어떤 스킬이 무엇을 하는지 설명하거나 단계를 건너뛰라고 추천하기 전에, 해당 스킬의 SKILL.md를 읽으십시오: 여기에 있는 요약은 참고용일 뿐입니다.

흐름(flow) 은 스킬들을 통과하는 경로입니다. 대부분의 경로는 하나의 메인 흐름을 따라가며, 두 개의 온-램프(on-ramp) 가 그 위로 합류합니다. 그 외 모든 것은 독립형이거나, 그 아래에서 실행되는 어휘 계층입니다.

메인 흐름: 아이디어 → 출시

대부분의 작업이 이동하는 경로입니다. 아이디어가 있고 그것을 구축하고 싶습니다.

1. /grill-with-docs 는 인터뷰를 통해 아이디어를 다듬습니다. 작업 디렉토리에서 작업 중일 때마다 여기서 시작하십시오: 상태 저장형이며, GLOSSARY.md 및 ADR에 학습한 내용을 보관합니다. (작업 디렉토리가 없나요? 대신 독립형에 포함된 /grill-me를 사용하십시오. 둘 다 동일한 /grilling 프리미티브를 실행합니다; grill-with-docs는 문서 흔적을 남기는 버전이므로, 저장소가 있는 상황에서는 항상 더 나은 선택입니다.)

2. 분기: 모든 질문을 대화로 해결할 수 있습니까? 질문에 실행 가능한 답변(상태, 비즈니스 로직, 직접 봐야 하는 UI)이 필요하다면, 프로토타입을 통해 우회하고, 양방향으로 /handoff 로 연결하십시오 (프로토타입은 자체 디렉토리에 존재하며, 이것이 정확히 /handoff의 용도입니다; 단계 경계 참조):

   • /handoff 로 나간 후, 해당 파일에 대해 새 세션을 열고,
   • /prototype 으로 임시 코드로 질문에 답한 후,
   • 배운 내용을 /handoff 로 다시 가져와 원래 아이디어 스레드에서 참조합니다.

3. 분기: 여러 세션이 필요한 빌드입니까?

   • 예 → /to-spec (스레드를 명세(spec)로 변환), 그런 다음 /to-tickets 로 분할하여 각각의 차단 에지(blocking edges) 를 선언하는 트레이서 불릿 티켓(tracer bullet ticket)을 만듭니다. 그런 다음 티켓을 두 가지 방법 중 하나로 작업합니다:
     • 티켓당 /implement 를 실행하고, 각 티켓 사이에 /clear 로 컨텍스트를 지웁니다. 로컬 트래커에서는 .scratch/<feature>/issues/ 아래에 티켓당 하나의 파일로, 수동으로 차단기가 완료된 순서대로 작업합니다; 실제 트래커에서는 에지가 기본 차단 링크가 되므로 차단기가 완료된 모든 티켓을 가져올 수 있습니다. 각 티켓은 자체 포함되어 있으므로 마지막 티켓의 컨텍스트는 폐기 가능합니다.
     • 전체 명세에 대해 한 번에 /implement-spec 를 실행합니다. 티켓을 작업 그래프(task graph) 로 읽고, 준비된 프론티어(frontier) 에 걸쳐 구현 하위 에이전트를 병렬로 실행한 후 모든 것을 하나의 통합 브랜치(integration branch) 에 통합합니다. 각 티켓을 직접 구동하는 대신 빌드를 오케스트레이션하려는 경우에 사용하십시오.
   • 아니오 → 동일한 컨텍스트 창에서 바로 /implement 를 실행합니다.

   어느 쪽이든, 코드는 /tdd (한 번에 하나의 적-그린 슬라이스)를 구동하고 /code-review (표준 + 명세의 2축 검토)로 마무리하여 빌드됩니다. /implement는 각 티켓에 대해 둘 다 실행합니다; /implement-spec의 구현자는 각자 /tdd를 구동하고, 통합 브랜치에 대해 하나의 /code-review를 실행합니다. 전체 명세 없이 테스트 우선 방식으로 구체적인 동작만 빌드하려면 /tdd 를 단독으로 사용하고, 고정된 지점에 대해 브랜치나 PR을 검토하려면 /code-review 를 단독으로 사용하십시오.

   작업이 풀 리퀘스트(PR)로 올라가면, /pr 이 본문을 구성합니다: 변경 사항을 보여주는 가장 작은 시각 자료, 작동하는 전후 증거, 단방향 또는 양방향 결정 호출(door call). 이는 모델 호출형이므로, 에이전트가 PR을 작성할 때마다 이를 사용합니다.

4. /retro 가 루프를 종료합니다. 빌드 후, 특히 잘못된 방향으로 진행된 경우, 세션을 되돌아보고 코드가 아닌 에이전트의 환경(environment) 에 대한 변경 사항을 제안합니다: 탐색 포인터, 자동화된 검사, /code-review가 시행하는 코딩 표준, 스티어링 파일, 도구. 기계적인 실수는 결정론적 검사가 되고; 판단 호출은 코딩 표준이 됩니다. 다음 빌드는 더 나은 환경에서 시작됩니다.

컨텍스트 위생

1~3단계를 하나의 끊어지지 않은 컨텍스트 창에 유지하십시오 (/to-tickets 이후까지 압축하거나 지우지 마십시오). 그래야 그릴링, 명세, 티켓이 모두 동일한 사고 위에 구축됩니다. 각 /implement는 그런 다음 새로 시작하여 티켓에서 작업합니다. /retro는 되돌아볼 세션에서, 지우기 전에 실행하십시오; 지운 후에는 대신 해당 세션의 로그를 가리키십시오.

이에 대한 한계는 스마트 존(smart zone) 입니다: 모델이 여전히 예리하게 추론하는 창(최첨단 모델에서 약 150k 토큰). 세션이 /to-tickets 전에 이에 도달하면, 성능이 저하된 상태로 진행하지 말고 가장 가까운 단계 경계에서 /compact를 실행하고 계속 진행하십시오 (단계 경계 참조).

온-램프

작업을 생성한 다음 메인 흐름에 합류하는 시작 상황입니다.

• 버그와 요청이 쌓이는 경우 → /triage. 이슈를 트라이지 역할을 통해 이동시키고 에이전트 준비 완료된 이슈를 생성하며, 나중에 /implement 가 이를 처리합니다.

  트라이지는 사용자가 생성하지 않은 이슈에만 해당됩니다: 버그 리포트, 들어오는 기능 요청, 날것 그대로 도착하는 모든 것. /to-tickets이 생성한 티켓은 이미 에이전트 준비 완료되었으므로 트라이지하지 마십시오.

• 무언가 고장난 경우 → /diagnosing-bugs. 어려운 버그를 위해: 한눈에 파악되지 않는 버그, 간헐적인 플레이크, 두 개의 알려진 정상 상태 사이에 스며든 회귀. 단단한 피드백 루프 (이 버그에서 이미 빨간색이 되는 단일 명령)가 있을 때까지 이론화를 거부한 다음 회귀 테스트로 수정합니다. 수정이 완료되면 동일한 세션에서 /retro 를 실행하여 버그를 방지했을 것을 묻습니다. 실제 발견 사항이 버그를 잠글 좋은 지점(seam)이 없다는 것이라면, /improve-codebase-architecture 의 작업입니다.

• 거대하고 불투명한 작업: 한 세션에 너무 큰 그린필드 프로젝트 또는 대규모 기능 빌드 → /wayfinder. 여기서 가장 인지적으로 까다로운 흐름입니다. 여기서 목적지까지의 경로가 아직 보이지 않을 때, 이슈 트래커에 의사 결정 티켓(decision tickets) 의 공유 지도(shared map) 를 작성하고 하나씩 해결하여, 안개가 걷히고 경로가 명확해질 때까지 결정, 산출물이 아닌 을 생성합니다. /grill-with-docs 가 한 세션에 담을 수 있는 아이디어를 다듬는 반면, wayfinder는 담을 수 없는 아이디어를 위한 것이며, 더 느리고 밀도가 높으므로 정확히 그 경우에만 사용하고, 잘 범위가 지정된 기능에는 사용하지 마십시오.

  지도가 명확해지면, 빌드하지 않고 인계합니다: /to-spec 에서 메인 흐름에 합류하여 지도의 연결된 결정을 빌드 가능한 계획으로 축소한 다음, 평소처럼 /to-tickets 및 /implement로 진행합니다. 지도를 /implement로 직접 루핑하면 해당 축소를 건너뛰고 연결된 세부 사항을 버리므로, 작업이 정말로 작은 것으로 판명된 경우에만 /implement로 직접 가십시오.

코드베이스 건강

기능 작업이 아닌 유지 보수입니다.

• /improve-codebase-architecture 는 에이전트가 작업하기 좋은 코드베이스를 유지하기 위해 여유 시간이 있을 때마다 실행합니다. 심화 기회(deepening opportunities) 를 표면화합니다; 하나를 선택하면 /grill-with-docs에서 메인 흐름으로 가져갈 수 있는 아이디어가 생성됩니다. 후보를 찾는 설문 조사입니다; /codebase-design (아래)는 선택한 후보를 설계하는 벤치입니다.

그 아래의 어휘

다른 스킬 아래에서 실행되는 두 개의 모델 호출형 참조이며, 각각 해당 어휘의 단일 진실 공급원입니다. 프로세스가 아닌 단어가 문제일 때 직접 사용하거나, 위의 스킬이 이를 가져오도록 하십시오.

• /domain-modeling: 프로젝트의 도메인 언어를 다듬습니다: 모호한 용어에 도전하고, 과부하된 단어를 해결하며(세 가지 작업을 수행하는 "account"), 되돌리기 어려운 결정을 ADR로 기록합니다. 이는 /grill-with-docs가 GLOSSARY.md를 깨끗한 용어집으로 유지하기 위해 구동하는 적극적인 규율입니다.
• /codebase-design 은 모듈의 형태를 설계하기 위한 심층 모듈 어휘(module, interface, depth, seam, adapter, leverage, locality)입니다: 깨끗한 지점(seam)에서 작은 인터페이스 뒤에 많은 동작을 배치합니다. /tdd와 /improve-codebase-architecture가 모두 이를 사용합니다.

단계 경계

단계(phase) 는 세션 내 작업 덩어리입니다: 그릴링, 구현, QA. 두 단계 사이의 경계(boundary) 에서는 다섯 가지 옵션이 있으며, 이 중에서 선택하는 것이 이 전체 지도에서 가장 모호한 결정입니다:

• 계속(Continue): 그대로 유지합니다. 비용이 없고, 손실이 없습니다.
• /clear: 다음에 중요한 것이 여기에 없을 때 창을 비웁니다.
• /handoff 는 휴대용 마크다운 파일을 작성합니다. 좁은 용도: 새로운 하네스, 새 디렉토리, 동료, 또는 단계 중간에 사이드 태스크를 포크할 때만. 휴대성을 얻습니다.
• 하위 에이전트(Subagent): 범위가 좁은 작업을 자체 창으로 보내고 보고서를 받습니다.
• /compact 는 이 컨텍스트를 압축하고 새 세션을 시드합니다. 트리 아래쪽이 아닌 기본값입니다.

정렬된 트리에 대해서는 PHASE-BOUNDARIES.md를 읽으십시오: 다섯 가지 질문, 각 분기 뒤의 추론, 그리고 1차 소스 비용이 계속을 먼저 배제해야 하는 이유. 경계에서 결정을 내리십시오; 단계 중간에는 계속하거나 나머지를 하위 에이전트로 분할하십시오.

독립형

메인 흐름에서 완전히 벗어납니다.

• /grill-me: /grill-with-docs와 동일한 끊임없는 인터뷰이지만, 상태 비저장형(state-less) 입니다: 로컬에 아무것도 저장하지 않고 GLOSSARY.md를 구축하지 않습니다. 작업 디렉토리에서 작업하지 않을 때 (계획, 설계, 글쓰기 등 저장소 아래에 없는 모든 것) 사용하십시오. 작업 디렉토리에 있다면 대신 /grill-with-docs를 사용하십시오: 동일한 인터뷰를 실행하고 문서 흔적을 남기므로 엄격히 더 좋습니다.
• /grilling 은 인터뷰 프리미티브 자체입니다: 라운드, 프론티어, 사실은 에이전트의 작업이고 결정은 여러분의 것입니다. /grill-me와 /grill-with-docs는 두 가지 명명된 진입점이며, /triage, /wayfinder, /improve-codebase-architecture는 모두 내부적으로 이를 실행합니다. 래퍼 없이 인터뷰를 원할 때만 직접 사용하십시오.
• /prototype 은 하나의 설계 질문에 답하는 작은 임시 프로그램입니다: 이 상태 모델이 올바른지, 또는 이 UI가 어떻게 보여야 하는지. 임시(throwaway)라는 것은 코드 작성 방식에 대한 제약일 뿐, 파괴하겠다는 약속이 아닙니다: 답은 실제 코드에 통합되고, 프로토타입 자체는 구현 이슈에서 참조되는 prototype/<name> 브랜치에 1차 소스로 보관됩니다. 메인 흐름의 2단계에서 우회로이지만, 설계 질문이 문서상으로 해결하기 어려울 때마다 사용하십시오.
• /research: 읽기 작업을 백그라운드 에이전트에 위임합니다: 1차 소스에 대해 질문을 조사한 다음, 인용된 마크다운 파일을 저장소에 남깁니다. 읽는 동안 계속 작업하십시오. 생성된 파일은 /grill-with-docs에서 메인 흐름 으로 가져갈 내용이며, 리서치가 사고를 대체하지 않고 보완하기 때문입니다.
• /to-questionnaire 는 여러분을 막고 있는 것이 머릿속이나 코드베이스가 아니라 다른 사람의 머릿속에 있을 때 사용하며, 그들이 작성할 설문지를 생성합니다. /grill-me의 역입니다: 주제에 대해 여러분을 인터뷰하는 대신 발신(send) (누구에게 가는지, 무엇을 돌려받아야 하는지)에 대해 인터뷰하고 질문을 격차에 맞춥니다. 돌아오는 것은 /grill-with-docs 또는 /to-spec의 자료입니다.
• /wizard 는 인간만이 할 수 있는 단계를 위한 것입니다: 인프라 프로비저닝, 자격 증명 또는 CI 시크릿 설정, 익숙하지 않은 타사 대시보드 클릭, 일회성 마이그레이션 또는 전환 실행. 각 URL을 열고, 각 값을 캡처하고, .env 및 GitHub 시크릿에 기록하는 대화형 bash 스크립트를 생성하므로 절차가 더 이상 에이전트에게 매번 다시 설명해야 하는 것이 아닙니다. 모델 호출형이므로, 에이전트가 여러분만이 통과할 수 있는 벽에 부딪히는 순간 이를 사용합니다. 에이전트가 스스로 할 수 있다면 그래야 합니다; 이것은 인간이 진정으로 루프에 있는 경우를 위한 것입니다.
• /wait-what 은 메시지가 전달되지 않았을 때의 교정입니다. 대화 중, 다른 스킬 내에서 사용하면, 에이전트는 GLOSSARY.md 어휘를 사용하여 평이한 영어로, 여러분이 놓친 컨텍스트를 포함하여 방금 말한 내용을 다시 제시합니다. 사후에 작동합니다; /grill-with-docs는 사전 치료법이며, 조기에 합의된 공유 언어가 전문 용어의 도착 자체를 막기 때문입니다.
• /teach: 현재 디렉토리를 상태 저장 작업 공간으로 사용하여 여러 세션에 걸쳐 개념을 학습합니다.
• /writing-for-agents 는 에이전트가 소비하는 문서(스킬, AGENTS.md, 가리키는 문서)를 작성하기 위한 참조입니다.

사전 조건

/setup-matt-pocock-skills: 첫 번째 엔지니어링 흐름 전에 실행하여 다른 스킬이 가정하는 이슈 트래커, 트라이지 레이블 및 문서 레이아웃을 구성합니다. 사용자 정의 이슈 트래커도 작동합니다.