agentleFS
develeepdeveleep/dev-gongbang/skills/productivity/framing-problems/SKILL.md

framing-problems

Skill1 starsChanged 19 days agoMITView on GitHub

사용자가 원하는 것을 들고 왔을 때 바로 실행하지 않고, 의도·원인·제약을 정리한 "구체화 기록"을 사용자와 확정한 뒤 그 기록에 따라 작업을 이어 간다. 사용자가 구체화를 요청하거나, 실행 중인 프롬프트나 다른 스킬이 작업 전 구체화를 지시할 때만 사용한다. 일반 작업 요청에는 스스로 실행하지 않는다.

The file

Files
SKILL.md

Framing Problems

요청을 해법으로 옮기기 전에 해법을 고를 근거를 모아 "구체화 기록"으로 남기고, 사용자와 함께 확정한다. prompt-builder로 만든 프롬프트는 실행될 때 작업 전에 이 스킬을 호출할 수 있고, 그 작업은 확정된 기록에 따라 이어진다.

핵심 규칙

  1. 사실은 조사하고, 결정은 묻는다. 코드, 문서, 로그, git 기록, 대화(이 스킬을 호출한 프롬프트 포함)로 답할 수 있는 것은 조사해서 출처(파일 경로, 문서 이름, URL)와 함께 보여 준다. 의도, 만족 기준, 선택은 사용자에게 묻는다. 조사로도 답으로도 채우지 못한 칸은 "미확인"으로 남긴다.
  2. 사용자가 "맞다"고 한 칸만 확정한다. 조사한 사실도 사용자가 맞다고 해야 확정된다. 호출한 프롬프트·스킬의 지시는 사용자 대신 결정할 권한이 아니다.
  3. 결정을 바꾸는 모호한 점을 묻는다. 기준 없는 표현("빠르게", "깔끔하게"), 해석이 둘 이상인 말, 범위가 정해지지 않은 대상 가운데 답에 따라 목표·해법·제약이 달라지는 것을 묻는다. 답이 어느 쪽이든 결정이 같으면 "미확인"으로 둔다.
  4. 제안된 해법은 보류한다. 요청이나 호출한 프롬프트에 해법이 있으면("여기 고쳐줘") "R5 제안 해법"에 적고, 그 해법이 풀려는 문제부터 맞춘다. 보류는 사용자가 R5에서 고르기 전까지 확정하지 않는다는 뜻이다. 조사한 원인이 제안 해법을 뒷받침하면 첫 메시지부터 유력 후보로 추천하고, 뒷받침하지 않으면 그 이유를 보여 준다.
  5. 넓은 조사는 일찍 백그라운드로 돌린다. 여러 파일을 훑는 조사와 R4를 채울 때의 웹 조사는 새 컨텍스트로 서브에이전트를 띄워 돌리고, 그 결과에 기대지 않는 질문부터 보낸다. 서브에이전트에게 사실마다 출처를 붙이게 하고, 출처 없이 온 내용은 "가설"로 적는다. 서브에이전트를 띄울 수 없으면 직접 조사한다.

주의할 점

  • 선택지를 보여 주는 질문 도구로 선택창을 띄우면 같은 메시지의 텍스트 질문은 사용자가 건너뛰기 쉽다. 한 메시지에 서술형 질문이 하나라도 있으면 그 메시지의 질문은 모두 텍스트로 묻거나, 서술형을 선택지 + 기타(자유 입력)로 바꾼다.

항목

R1~R6은 마무리 전에 모두 채울 체크리스트다. 칸은 frontier(아래 "질문 방식")가 닿는 대로 어느 순서로든 채운다. 시작할 때 체크리스트를 보여 주고, 단계의 칸이 모두 확정되면 갱신한다.

구체화 진행:
- [ ] R1 의도·배경
- [ ] R2 이상·현재·원인
- [ ] R3 제약·자원
- [ ] R4 외부 근거
- [ ] R5 목표·해법
- [ ] R6 부작용·장애물
  • R1 의도·배경: 왜 하려는지, 계기(특정 사건 또는 반복 상황), 누가 겪는지. 요청이 해법만 말하면 "이걸 바꾸면 무엇이 달라지길 바라나요?"처럼 해법 뒤의 의도를 묻는다.
  • R2 이상·현재·원인: 이상(관찰할 수 있는 기준)과 현재는 따로 묻고 따로 적는다. 현재는 코드, 출력, 로그로 직접 확인한다. 문제를 "이상은 X인데 현재는 Y다"로 쓰고, 원인을 "확인됨" 또는 "가설"로 적는다.
  • R3 제약·자원: 바꿀 수 없는 조건(기술, 일정, 조직, 호환성)과 그대로 쓸 기존 코드·도구·문서. 재사용 후보는 목록으로 보여 준다.
  • R4 외부 근거: 보안·결제·개인정보·규제처럼 틀리면 비용이 큰 표준이 있는 영역이거나, R3에 따라 할 기존 방식이 없거나, 사용자가 요청할 때 채운다. 그 밖에는 "R4 해당 없음: 이유"를 한 줄 적고, 사용자가 원하면 채운다. 채울 때는 알려진 해법과 표준마다 우리 상황에 맞는지(맞음 / 조건부 / 맞지 않음)와 그 판단의 근거 칸(R1~R3), 출처 URL을 적는다. 웹 검색 도구가 없으면 그렇다고 알리고 출처를 "모델 지식, 미검증"으로 적는다.
  • R5 목표·해법: 목표(바꿀 원인)와 해법(바꾸는 방법)을 따로 정한다. 어떤 원인을 바꾸는지 적은 후보 2~3개(제안 해법, R3 자원을 쓰는 해법, R4에서 온 해법)를 비교한다. 목표 원인이 "가설"이면 확인 방법(재현, 측정, 로그)을 R6 장애물에 넣고, 가설이 틀리면 R2로 돌아간다.
  • R6 부작용·장애물: 해법이 새로 만드는 비용·위험(건드리는 호출부, 설정, 결과를 쓰는 사람)과 실행을 막는 것(권한, 의존성, 일정). 부작용마다 감수 / 완화책 / 해법 변경을 정한다. 감수할 수 없으면 R5로 돌아간다.

질문 방식

메시지마다 frontier를 묻는다. frontier는 답이 기대는 칸이 이미 확정돼 지금 물을 수 있는 질문 전체다. 보통 첫 메시지에서 R1·R2·R3을 함께 묻고, R5 해법은 R2 원인, R3 제약, R4 판정(채우는 경우)이 확정된 뒤 묻는다. 조사로 찾은 사실은 첫 메시지에 바로 보여 준다. 다른 질문의 답에 따라 달라지는 질문은 그 답을 받은 다음 메시지에서 묻는다.

**R2·R3 · 질문 2개 · 답이 필요합니다**

### R2 이상·현재·원인
- 현재: 배포 스크립트가 **체크리스트를 읽지 않는다** (`scripts/deploy.sh`)
- 원인: 스크립트에 확인 단계가 없음 (**확인됨**)

❓ **Q1 - 빠지는 항목**: "자꾸 빠진다"는 항목은 매번 같은가요? (a) 특정 항목 (b) 매번 다름 (c) 모름

➡️ 추정: (a). 배포 명령과 따로 하는 항목(공지, 롤백 계획)이 잊히기 쉬움

---

### R3 제약·자원
❓ **Q2 - 배포 경로**: 배포는 `scripts/deploy.sh`로만 하나요? 다른 경로가 있으면 스크립트에 확인 단계를 넣어도 빠지는 배포가 생깁니다.

➡️ 네. 근거: 저장소에 다른 배포 스크립트가 없음

**확인**: 위 정리와 추천이 맞으면 "맞다", 다르면 번호로 알려 주세요(예: "Q1 b").
  • 진행 줄: 첫 줄에 다루는 단계와 질문 수를 적어, 알림만 봐도 답이 필요한지 알게 한다. 정리에서는 확정하려는 값만 굵게 한다.
  • 추천: 모든 질문에 ➡️ 추천과 근거를 달고, "네"가 추천을 받아들이는 뜻이 되게 묻는다. 근거가 조사한 사실이나 확정한 칸이 아니면(의도, 계기, 실패 사례, 운영 절차·승인·일정처럼 사용자만 아는 것) 추천 앞에 "추정:"을 붙인다. 사용자가 모를 수 있으면 "모르면 확인 방법을 R6 장애물에 넣음"을 함께 적는다.
  • 확인: 마지막 줄은 확인 요청이다. "맞다"는 정리와 모든 추천을 받아들인다는 뜻이다. 추천과 다른 답이나 새 정보가 오면, 반영한 정리를 다음 메시지 맨 앞에 넣어 다음 질문과 함께 확인받는다. 정리만 담은 메시지는 더 물을 질문이 없을 때 보낸다.
  • 메시지의 질문이 모두 선택형이면 선택지를 보여 주는 질문 도구가 있을 때 그것으로, 없으면 번호 목록으로 묻는다("주의할 점" 참고). 추천은 첫 선택지에 두고 라벨 끝에 "(추천)"을 붙인다. 질문이 4개를 넘으면 텍스트로 묻는다.
  • 압축 모드: 사용자나 호출한 프롬프트·스킬이 질문을 줄여 달라고 하면, 조사로 채운 구체화 기록 전체와 모든 단계의 질문을 한 메시지에 보여 준다(진행 줄 **R1~R6 한 번에 · 질문 <개수>개 · 답이 필요합니다**). 확정 전 칸은 "확인 필요"로 표시하고, 사용자는 한 번의 답으로 여러 단계를 확정할 수 있다. R6 부작용·장애물과 "가설"인 원인은 질문에 남긴다.
  • 중단: 사용자가 멈추라고 하면("그냥 해줘", "그만 묻고 진행해") 더 묻지 않고 지금까지의 기록을 보여 준다. 못 채운 칸은 "미확인"으로 둔다. R5 해법이 미확인이면 제안 해법을 따르고 그렇다고 한 줄로 알린다. "가설"인 원인과 미확인 R6 때문에 생길 수 있는 위험은 한 줄씩 알린다.

되돌아가기

사용자가 확정한 내용을 바로잡으면("그게 아니고", "그런 뜻이 아니라") 다음 순서로 처리한다. 기록을 확정해 다른 작업으로 넘어간 뒤에도 같다.

  1. 정정이 어느 단계의 전제인지 찾아, 그 단계를 바뀐 전제로 다시 확정한다.
  2. 그 뒤 단계를 순서대로 다시 본다. "근거" 열에 바뀐 칸이 있는 결정은 다시 판단하고, 없는 결정도 결론이 여전히 성립하는지 확인한다.
  3. 결과를 한 줄씩 보여 준다. 예: R3 유지: 제약이 의도와 무관함 / R5 변경: 캐시 추가 → 타임아웃 재시도.

이미 정한 해법도 바뀐 전제로 다시 판단한다. 정정을 조건이나 예외 하나로 덧붙여 해법을 지키면 이전 의도를 계속 따르게 된다. 정정이 표현(용어, 문장)에 대한 것이면 그 칸만 고친다.

구체화 기록

## 구체화 기록
| 항목 | 내용 | 출처 | 근거 |
|---|---|---|---|
| R2 이상 | 관찰할 수 있는 기준으로 | 사용자 | R1 의도 |
| R2 원인 | (확인됨 / 가설) | `경로` | R2 현재 |
  • 항목: R1 의도, R1 계기, R2 이상, R2 현재, R2 문제, R2 원인, R3 제약, R3 자원, R4 근거, R5 제안 해법(채택 / 기각), R5 목표, R5 해법, R6 부작용, R6 장애물. 값이 여럿이면 행을 나눈다.
  • 출처: "사용자", 확인한 파일·문서·URL, 또는 "미확인".
  • 근거: 이 칸의 결정이 기대는 다른 칸. 되돌아가기에서 다시 볼 칸을 찾는 데 쓴다.

마무리

  1. R1~R6의 모든 칸이 정해지면, 기록 전체를 한 번 보여 주고 확정받는다.
  2. 프롬프트나 다른 스킬이 호출했으면, 확정된 R5 목표와 해법에 따라 그 지시의 작업을 이어 간다.
  3. 직접 호출됐으면 R5 해법을 실행할지 묻고, 답을 받기 전에는 실행하지 않는다.

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.