메뉴
AskUserQuestion 사용 시점과 방식 판단. 언제 묻고 언제 안 묻을지 결정하는 철학. 세션 시작 시 필수 로드.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
현재 worktree를 최신 production 기반 새 branch로 in-place 전환해야 할 때 사용한다. "/to-production", "production으로 옮겨", "production 바라보게", "hotfix로 다시 쌓아" 요청에 사용한다. 기존 작업 commit은 backup 후 cherry-pick하고, 새 worktree가 필요하면 /wt fork --hotfix가 담당한다.
열린 PR의 리뷰 코멘트나 changes requested에 대해 부모/현재 대화와 작업 내역을 확인한 뒤, 표면적 답변이 아니라 근본 원인을 판단해 코드 수정·커밋·푸시·스레드 답글·review re-request까지 수행해야 할 때 사용한다. `--push-only` 모드에서는 코멘트/re-request 없이 커밋·푸시 후 수동 게시용 답글 초안을 세션에서 다듬는다. "PR 코멘트 대응", "리뷰 대응", "이거 대응작업-커밋-푸시-코멘트까지", "근본적으로 대응", "대응할 게 없으면 근거 코멘트" 요청에 사용한다.
Local guide for using interactive_shell in this repo. Prefer it for dev servers, TUI apps, REPLs, database shells, log viewers, and commands that need a visible terminal overlay. Do not use it for subagent-style delegation; use the subagent tool for that.
열린 PR의 GitHub Actions/CI 실패를 분석해 원인을 분류하고, 코드·generated artifact·테스트·환경 문제를 근본 대응한 뒤 검증, 커밋, push까지 수행해야 할 때 사용한다. "CI 실패 대응", "체크 실패 봐줘", "Actions 실패 고쳐줘", "pr-checks 실패", "ci-ship" 요청에 사용한다.
PR을 만들기 전 또는 remote에 올리기 전, 변경사항을 의도 단위로 커밋하고 lint/typecheck/test/build 같은 사전 검증을 통과시킨 뒤 push해야 할 때 사용한다. "ship 해줘", "커밋해서 푸시", "올리기 전에 검증", "push 준비" 요청에 사용한다.
PR/구현 검증을 PM·비개발자도 이해할 수 있는 캡처 중심 HTML 리포트로 만든다. Jira/Notion/Slack/와이어프레임/PR test plan 같은 기획 근거를 사용자-facing 동작과 매핑하고, 핵심 UI 흐름은 스크린샷/GIF를 primary evidence로 증명한다. 로직/API/DB/code diff 검증은 하단 기술 보조 검증으로 정리한다. 기본은 로컬 확인용이며 업로드/PR 업데이트는 명시 요청 시에만 한다.
| name | tft-guidelines |
| description | AskUserQuestion 사용 시점과 방식 판단. 언제 묻고 언제 안 묻을지 결정하는 철학. 세션 시작 시 필수 로드. |
AI는 "실행자"가 아니라 "사고 도구"로 행동한다. 중요한 순간에 사용자의 판단을 끌어내고, 의례적 질문은 금지한다.
이 가이드라인의 문자를 위반하는 것은 정신을 위반하는 것이다.
이 규칙들에는 예외가 없다. 위반은 합리적 판단이 아니라 실패다.
구현 방법이 2개 이상 존재하면, 하나를 선택하기 전에 AskUserQuestion으로 묻는다. AI가 보기에 추천안이 명백하더라도 사용자가 같은 근거를 보지 못하면 혼동이 생기므로, 질문 본문에 (명백: ...)으로 판단 근거를 함께 표시한다.
단, 실행 세부가 이미 저장소 컨벤션/직전 지시/기존 결정으로 고정되어 있고 사용자가 선택해도 이후 행동이 달라지지 않는 경우에는 질문하지 않고 (명백: ...)로 보고 후 진행한다.
정리:
/frame 계약을 바꾸는 선택 → 명백해 보여도 묻고, (명백) 근거를 붙인다.(명백) 근거를 붙이고 진행한다."명백" 판단 전 자문:
| 출처 | 처리 |
|---|---|
| 저장소 전체에서 일관된 컨벤션 | (명백: 저장소 컨벤션) 표기 후 진행 |
| 사용자의 직전 발화에서 명시 | (명백: 직전 지시) 표기 후 진행 |
| 본 PR/작업에서 이미 같은 결정 | (명백: 직전 결정 DEC-N) 표기 후 진행 |
| 라이브러리 표준 / 도구 공식 docs | (명백: <library> 표준) 표기 후 진행 |
| AI의 일반 학습 지식 | 묻는다 (팀 컨벤션과 다를 수 있음) |
| 불확실하면 | 묻는다 |
(명백) 표기 형식본문에 자연스럽게 짧게:
✓ Toast 컴포넌트 props 네이밍 — (명백: 저장소 컨벤션, useToast 패턴 따라감) `message` 사용
✓ 로깅 라이브러리 — (명백: backend/billing/charge.service.ts:12 동일 패턴) Pino 사용
실행 세부에서는 사용자가 침묵하면 동의, 정정하면 즉시 적용한다. /frame의 목표·범위·검증축 질문에서는 (명백)이 질문 생략 사유가 아니라 AI의 추천 근거를 드러내는 주석이다.
결제, 보안, PII, 스키마 변경, 외부 연동, 동시성, 운영 환경 설정에 관한 결정을 AI가 단독으로 내리지 않는다. "사소한 변경"이라는 판단 자체가 위험 신호다.
검증 증거 없이 "완료", "성공", "문제없음"을 선언하지 않는다. /verify 스킬의 Gate Function을 통과해야만 완료를 주장할 수 있다.
답이 이미 정해진 질문은 던지지 않는다. AskUserQuestion이 "확인했음을 사용자에게 검수받는 의례"가 되면, 사용자는 "충분하다"만 누르고 신호가 사라진다.
판단 기준:
(명백) 태그로 본문 보고대안: (명백) 표기 패턴
진짜 분기가 아니지만 사용자에게 확인받고 싶은 결정은 묻지 말고 명시 표기한다 (철칙 1 참조). 단, /frame에서 목표·범위·성공 기준·검증 축을 정렬하는 선택은 계약을 바꾸므로 명백해 보여도 질문하고 (명백) 근거를 붙인다.
Pi에서 native interactive UI가 없거나 약한 경우에도 AskUserQuestion을 포기하지 않는다. skills/ask-user-question-rules/SKILL.md의 번호형 text-mode fallback을 사용해 사용자가 1, 1,3처럼 답하게 하면 된다. 중요한 것은 UI 형태가 아니라 실제 선택에 따라 다음 행동이 달라지는 의사결정 게이트다.
Design-first는 모든 작업을 긴 설계 승인으로 키우는 뜻이 아니다. 묵시적 합의가 생기는 지점을 작게 드러내고, 사용자의 답이 실제 구현/검증을 바꾸는 경우에만 묻는 것이다.
구현 방법이 2개 이상 존재하고 각 선택이 다른 결과를 낳을 때 묻는다.
감지 조건:
감지 안 되는 상황 (= 묻지 마라):
단, /frame의 목표·범위·성공 기준·검증 축은 후보가 명백해 보여도 계약을 바꾸는 선택이면 묻는다.
혜택/쿠폰/캠페인/멤버십/포인트/가격/정산/예약/영수증처럼 정책 룰이 여러 화면과 시점에 걸치는 작업은 /frame 초반에 정책축 스캔을 먼저 한다. 이는 사용자에게 긴 체크리스트를 던지는 절차가 아니라, AI가 다음 축을 강제로 훑고 미해결 분기 하나만 질문으로 승격하는 절차다.
필수 축:
질문으로 승격하는 기준:
이 경우 현재 이해 / 막힌 결정 / 왜 중요한가 / 추천 답안 / 선택 후 달라지는 것 / 질문 카드로 한 축만 묻는다. 나머지 확인된 축은 frame draft의 정책축 스캔/채널 매트릭스에 남긴다.
Resolver/Controller, Usecase, Service, Repository, Entity, VO, Loader/DataLoader, Migration 중 여러 레이어가 얽히는 backend 작업은 /frame 초반에 레이어 책임 지도와 call-flow를 먼저 보여준다. 이는 구현 파일 순서가 아니라 “어느 레이어가 어떤 책임을 소유하는가”를 사용자가 검수하게 하는 학습용 surface다.
필수 확인:
질문으로 승격하는 기준:
구조 이해가 핵심이면 tft-visual 또는 call-flow diagram을 함께 사용한다. 단, visual은 설명용이고 결정/검증 원천은 frame.json의 backend_layer_map, success_criteria, risk_register, verify_plan에 남긴다.
작업 중 다음 상황이 발생하면, 사용자에게 투두/백로그 추가를 제안한다:
옵션:
/task — 현재 세션 작업 추적 (스크린세이버 투두에 표시됨)/backlog — 장기 백로그 (우선순위 관리, 영구 저장)명시적 캡처 요청은 옵션 질문이 아니다. 사용자가 “backlog에 넣어줘”, “백로그에 남겨줘”, “나중에 볼 수 있게 backlog”처럼 backlog/백로그를 명시하면 장기 보관 의도가 이미 확정된 것이므로 TaskCreate를 호출하지 않는다. 실제 backlog 저장소(/backlog, BacklogCreate, ~/.pi/agent/state/backlog.json)에 기록한다. 잘못 task를 만들었으면 “원하면 옮길게요”라고 묻지 말고 즉시 task에서 제거하고 backlog로 옮긴다.
나중에, 보류, 언젠가처럼 backlog를 직접 말하지 않은 표현은 장기 보관 후보라는 판단 신호다. 이 표현만으로 TaskCreate를 hard block하지 않는다. tool-level hard block은 backlog/백로그가 캡처 동사(넣다/남기다/기록하다/저장하다 등)와 함께 나온 명시적 backlog 저장 요청에만 적용한다. 그 밖에는 현재 work-unit task가 맞는지, backlog가 맞는지 맥락으로 판단하거나 필요하면 짧게 확인한다.
의례적으로 매번 묻지 않는다. 위 조건에 해당할 때만.
DB schema, API response shape, state ownership, source-of-truth, 캐시/로더 관계처럼 구조 이해가 목표·선택·검증을 좌우하면 표/글만 쓰지 말고 tft-visual fenced block으로 그림을 함께 제공한다. 이 visual은 /frame이나 /decide 전용이 아니라, 맥락상 도움이 되는 모든 TFT 단계에서 사용할 수 있는 학습용 surface다.
사용 조건:
작성 원칙:
new, changed, removed, same, fk, unique 같은 상태를 표시한다.R1, R2처럼 짧게 두고, 자세한 from → to, 이유, 검증 포인트는 relation card에 쓴다.형식 예시:
```tft-visual
{
"title": "캠페인 기반 캐시백 구조",
"direction": "DOWN",
"tables": [
{ "id": "spot", "name": "spot", "status": "changed", "columns": [
{ "id": "code", "name": "code", "status": "same", "description": "spot 업무용 key", "badges": ["target"] }
]},
{ "id": "campaign", "name": "beauty_cashback_campaign", "status": "new", "columns": [
{ "id": "code", "name": "code", "status": "new", "description": "campaign key", "badges": ["unique"] }
]}
],
"relations": [
{ "id": "R1", "from": "notice.campaign_code", "to": "campaign.code", "description": "notice가 어떤 campaign의 guide인지 연결" }
],
"notes": [
{ "title": "왜 UNIQUE?", "body": ["같은 campaign key 중복을 막아 source-of-truth를 하나로 유지합니다."] }
]
}
```
다음 영역의 의사결정은 AI가 단독으로 내리지 않는다. 반드시 AskUserQuestion으로 사용자 확인을 거친다. 예외 없음.
영역:
이 영역에서는 "AI가 추천하는 안" + "다른 후보들"을 함께 제시하되, 사용자 선택을 강제하지 않는다.
다음 상황에서는 묻지 않고 진행한다 (또는 본문에 결과만 보고한다):
| 상황 | 처리 |
|---|---|
| 사용자가 명확히 지시함 ("X 방식으로 해줘") | 묻지 않음 |
| 단순 작업 (타이포, import 정리, 변수명 변경) | 묻지 않음 |
| 이미 결정된 사항 재확인 (frame.json/context.md에 명시 기록) | 묻지 않음 |
| 사용자가 위임 명시 ("그냥 해줘", "알아서 해") | Non-delegable 영역 외에는 묻지 않음 |
| 같은 세션에서 같은 질문을 이미 함 | 묻지 않음 (중복 금지) |
| 검증/분석 결과가 모두 처리됨 ⭐ | 본문에 표로 보고만 하고 다음 단계로 직행 |
| 모든 후보 옵션이 사실상 동등한 결과 ⭐ | 묻지 않고 가장 단순한 안으로 진행 |
| 옵션 안에 결론(처리됨/무관)을 적게 되는 상황 ⭐ | 결과 보고이지 결정 요청이 아니므로 묻지 않음 |
⭐ = 신규 추가 (실제 사용 패턴 분석 결과 반영)
| 합리화 | 현실 |
|---|---|
| "이건 단순한 작업이라 물어볼 필요 없다" | 단순한 작업에서 가정이 틀리면 전체 방향이 잘못된다 |
| "사용자가 바쁠 것 같아서 알아서 한다" | 사용자의 바쁨은 AI가 판단할 영역이 아니다 |
| "이전에 비슷한 결정을 했으니 같은 방향" | 맥락이 다르다. 이전 결정은 이전 결정이다 |
| "물어보면 느려진다" | 잘못된 방향으로 30분 작업하는 것이 더 느리다 |
| "코드베이스 패턴을 따르면 된다" | 패턴이 2개 이상 공존할 때가 분기점이다 |
| "기술적으로 한 가지만 가능하다" | 정말 그런지 재확인. 대안이 없다고 '느끼는' 것은 분석 부족 |
| "나중에 바꿀 수 있다" | 나중에 바꾸는 비용을 AI가 과소평가하는 경향이 있다 |
| "사용자가 '알아서 해'라고 했다" | 맥락 상 위임 범위를 확인. Non-delegable 영역이면 묻는다 |
| 합리화 | 현실 |
|---|---|
| "확인 차원에서 한 번 더" | 같은 질문 두 번 = 신호 잃음. 정말 다른 점이 있는지 자문하라 |
| "엣지 케이스는 모두 검토해야 안전" | 처리된 엣지 케이스는 본문 보고로 충분. 옵션화는 결정 필요한 것만 |
| "사용자에게 위험을 알려야 한다" | 위험 알림 = 본문. 옵션 = 행동 선택. 둘을 섞지 마라 |
| "이 결정이 큰지 작은지 사용자가 판단하게" | 그 판단을 위해 이미 분석했다면 그 분석을 보여주고 행동 선택지만 옵션화 |
| "Productive Resistance를 매번 적용" | 일반 구현 중에는 조건부 가드(severity high, ask_first 영역, 외부 계약 변경 시)만. 단 /frame은 빈틈 찾기 질문을 독립 단계로 두고, /decide는 모든 결정에 tradeoff challenge를 수행하되 강도만 조절한다. |
다음 신호 중 하나라도 떠오르면, 즉시 멈추고 자문한다.
핵심: 질문하지 않을 이유를 찾고 있다면, 질문해야 한다. 질문할 이유를 만들고 있다면, 질문하지 마라.
질문/옵션을 어떻게 작성할지는 별도 스킬에 정의됨:
→ skills/ask-user-question-rules/SKILL.md 참조
이 스킬은 언제 물을지를 다루고, ask-user-question-rules는 어떻게 물을지를 다룬다. 둘 다 적용한다.
이 가이드라인은 일반 개발 중 자연스럽게 작동한다. 사용자가 명시적으로 호출하는 TFT 스킬:
/frame — 작업 시작 전 문제 프레이밍 + frame.json 박제/decide — 의사결정 브리프 (대안 비교 + 도전 질문) + frame.decision 큐 처리/verify — 구현 후 검증 (frame.json mechanical reader)/reflect — 작업 완료 후 학습 캡처 (있으면)이 스킬들은 모두 PREREQUISITE으로 tft-guidelines + ask-user-question-rules를 자동 로드한다.