프롬프트 쿡북 — 상황별 요청 예시

복사해서 대괄호 [ ] 안만 바꿔 쓰세요. Claude Code는 /스킬이름, Codex CLI는 $스킬이름으로 시작합니다. 명령 예시의 $SK는 스킬 설치 폴더입니다(개발자 가이드 1-1). 예시 ID(SUP010, LD01 …)는 설명용입니다.

좋은 요청의 구성
읽기·이해 (파일을 바꾸지 않음)
만들기
고치기·진단
검증·테스트
운영·배포
스킬이 켜지지 않을 때
요청에 자주 붙이는 제약 문구

1. 좋은 요청의 구성

/스킬이름  [무엇을]  [어디에서(화면/모듈/파일)]  [제약]  [완료 기준 / 보고 형식]

요소	나쁜 예	좋은 예
무엇을	"화면 고쳐 줘"	"SUP010 조회 조건에 '상태' 콤보를 추가하고 LD01에 연결해 줘"
제약	(없음)	"기존 `LD01` 출력 순서는 바꾸지 마. DB 스키마 변경은 하지 말고 필요하면 알려 줘"
완료 기준	"잘 되게"	"hs_inspect ERROR 0, 변경한 JS는 node --check 통과, 실행하지 못한 검증은 '미수행'으로 적어 줘"

한 번에 한 층씩 요청하면 틀린 곳을 빨리 찾습니다(SQL → 거래 → 화면 JS → 화면 HTML).

2. 읽기·이해 (파일을 바꾸지 않음)

상황	프롬프트	기대 결과 / 확인할 것
화면 흐름 이해	`/handstack-source-trace [SUP010]의 [저장] 버튼이 어떤 거래와 SQL까지 가는지 단계별로 설명해 줘. 파일은 수정하지 마.`	이벤트 → 거래 → statement(id, seq) → 출력 대응. 알려 준 파일을 직접 열어 대조
기능 영향 범위	`/handstack-source-trace [LD01]을 수정하면 영향받는 화면과 거래를 모두 찾아 줘.`	호출 화면 목록. `AccessScreenID`에 걸린 팝업·공용 호출 포함 여부
복제 기준 찾기	`/handstack-feature-delivery [목록 + 등록 화면]을 만들 건데 같은 모듈에서 복제 기준 후보 3개를 비교해 줘. 아직 만들지 마.`	후보별 유사점/차이
설정 파악	`/handstack-host-operations 이 서버의 모듈 목록과 설정 파일 계층, 재시작이 필요한 설정을 표로 정리해 줘. 비밀 값은 열지 말고 키 이름만.`	표. 비밀이 출력되지 않았는지 확인
코드베이스 목록	(스킬 없이) `python $SK\handstack-source-trace\scripts\hs_inspect.py --root . --list`	화면 ID 목록

3. 만들기

상황	프롬프트	기대 결과 / 확인할 것
새 기능 계획	`(계획 모드) /handstack-feature-delivery [intent.md]와 [규칙 표]를 읽고 plan.md를 작성해 줘. 복제 기준, 연결표, 층별 변경 파일, 위험, 검증 계획 포함. DDL을 읽지 못한 컬럼은 추측하지 말고 질문해 줘.`	plan.md. 연결표의 입력/출력/권한이 비어 있지 않은지
SQL + 거래	`/handstack-transaction-contracts plan.md의 [LD01, MD01, DD01]을 .dbc/.txn으로 작성해 줘. 저장은 TransactionScope true, AccessScreenID는 [SUP010]. 컬럼은 DDL을 읽어서 써.`	파라미터 선언, `(id, seq)` 유일, 출력 순서. `hs_inspect` 재실행
부모-자식 저장	`/handstack-transaction-contracts [부모 그리드 + 자식 그리드]를 한 번에 저장하는 서비스를 만들어 줘. 부모 키를 자식에 전달해야 해.`	다중 seq + 키 전달 방식 설명
화면	`/handstack-screen-development [SUP010]을 [복제 기준 화면]의 구조로 만들어 줘. belongID에 거래 ID를 빠짐없이 넣고, 화면 상태 7가지를 모두 처리해.`	HTML/JS 쌍. `hs_inspect`, `design_lint`, `node --check`
조회 조건 추가	`/handstack-screen-development [SUP010]에 [상태] 조회 조건을 추가하고 기존 [LD01] 거래에 연결해 줘. 변경 영향 점검표 기준으로 고쳐야 하는 모든 층을 알려 줘.`	화면 + 계약 + 권한까지 같이 수정
서버 함수	`/handstack-function-contracts [외부 API를 호출해 결과를 반환하는 서버 함수]를 .fnc로 작성해 줘. 언어는 [C#]. 업무 오류는 Exception 출력으로.`	`.fnc` + 호출 화면 연결
외부 연동	`/handstack-external-contracts [파일 첨부 기능]을 추가해 줘. 크기 제한은 [10MB]. 확장자 제한은 서버가 검사하지 않으니 업로드 후 검증도 알려 줘.`	저장소 계약 + 한계 설명
AI 프롬프트	`/handstack-prompt-contracts [문의 내용을 분류]하는 .pmt를 만들어 줘. 판단 계약 형식으로, 선택지는 [3개].`	`.pmt` + decision 규칙 준수
서버 오케스트레이션	`/handstack-workflow-contracts [사용자 조회 → 주문 조회 → 결과 병합]을 한 번의 호출로 처리하는 워크플로를 설계해 줘. 각 단계에 검증을 넣고 응답에 포함할 단계를 정해 줘.`	`WorkflowSteps` 초안, 매핑, `Assertions`. `hs_inspect`로 점검
메뉴	`/handstack-module-development [SUP010]을 [메뉴 위치]에 등록하고 functions를 화면의 buttonCommand 분기와 맞춰 줘.`	메뉴 형식(두 가지 중 파일이 쓰는 형식 유지)

4. 고치기·진단

상황	프롬프트	기대 결과 / 확인할 것
오류 메시지	`/handstack-troubleshooting [SUP010] 조회 시 "[오류 문구 그대로]"가 나와. 첫 실패 층을 판정하는 순서와 확인할 파일을 알려 줘. 고치기 전에 원인부터 확정하자.`	층 판정 + 근거. 원인 확정 전 수정 금지
저장은 되는데 알림이 없음	`/handstack-troubleshooting [SUP010] 저장은 되는데 성공 알림이 안 떠.`	callback `undefined` 가능성 등 후보
수정이 반영 안 됨	`/handstack-troubleshooting 계약을 수정했는데 예전 동작이야. 서버가 읽는 파일, 캐시, 브라우저 캐시 순으로 확인법을 알려 줘.`	파일 위치·캐시 확인 절차
연결 불일치	`/handstack-source-trace [SUP010]의 hs_inspect 결과 [WARN 목록]을 해석해 줘. 실제 문제인 것과 오탐 후보를 구분해 줘.`	코드별 해석
서버 문제	`/handstack-host-operations 서버가 시작되지 않아. [로그 발췌]. 포트, 모듈 로딩, 설정 순으로 확인해 줘.`	확인 순서. 위험 명령 전 확인

5. 검증·테스트

상황	프롬프트	기대 결과 / 확인할 것
규칙 → 테스트	`/handstack-rules-and-verification [규칙 표]에서 테스트 케이스를 뽑아 줘. 경계, 대상 없음, 잘못된 입력, 권한 없는 계정, 동시 저장, 응답 유실 후 재시도 포함. 각 케이스에 수행 수준을 표시해 줘.`	테스트 표. "미수행"이 정직하게 표시되는지
조건이 많은 규칙	`/handstack-rules-and-verification [조건 4개]를 결정표로 만들어 줘. 완전성과 배타성을 검증하고 사유 우선순위를 제안해 줘.`	표 + 검증
동시 저장	`/handstack-rules-and-verification [MD01]이 동시에 두 요청이 와도 한도(5건)를 지키는지 검토해 줘. TransactionScope, 잠금 순서, 유일 제약 관점으로.`	위험 지점 + 개선안. 롤백은 예외일 때만이라는 점 반영
구현 후 자체 검토	`[plan.md]와 현재 변경을 비교해서 계획과 다른 부분, 빠진 검증을 보고만 해 줘. 수정하지 마.`	불일치 목록
변경 범위 점검	(스크립트) `git diff --name-only main...HEAD` 결과의 화면 ID마다 `hs_inspect.py --screen <ID> --fail-on ERROR`	변경된 화면만 통과

6. 운영·배포

상황	프롬프트	기대 결과 / 확인할 것
파이프라인 점검	`/handstack-cicd-pipeline 이 저장소의 빌드·배포 스크립트를 pipeline_lint 결과와 함께 점검하고 안전하지 않은 지점을 우선순위로 정리해 줘. 아무것도 실행하지 마.`	위험 목록 + 순서
파이프라인 설계	`/handstack-cicd-pipeline [Jenkins]로 [검증 환경 → 승인 → 운영] 파이프라인을 설계해 줘. 격리 스모크와 롤백, 릴리즈 기록 단계를 포함하고, 골격은 실제 도구에서 검증이 필요하다고 표시해 줘.`	단계·게이트 표 + 골격
배포 방식 선택	`/handstack-cicd-pipeline 서버 [3대], 변경은 [계약·정적 파일 위주]일 때 폴더 반영과 업데이트 패키지 중 무엇이 맞는지 근거와 함께 비교해 줘.`	비교 + 주의점(`contracts`는 업데이트 ZIP에 없음 등)
Docker 업데이트	`/handstack-cicd-pipeline ack 컨테이너를 새 이미지로 교체했는데 앱이 갱신되지 않아. 원인과 업데이트 정책을 알려 줘.`	볼륨 시드 규칙 설명
롤백 계획	`/handstack-cicd-pipeline [이번 배포]의 롤백 계획을 작성해 줘. DB 변경이 있으면 별도로 구분하고 리허설 절차도.`	되돌릴 대상, 순서, 확인
릴리즈 기록	`[템플릿 release-record.md]를 이번 배포 정보로 채워 줘. 비밀 값은 쓰지 말고 파일 이름만.`	기록 초안

7. 스킬이 켜지지 않을 때

프롬프트 첫머리에 스킬 이름을 씁니다(/handstack-… 또는 $handstack-…).
설치 위치 확인: 프로젝트(.claude/skills, .agents/skills) 또는 개인(~/.claude/skills, ~/.agents/skills). 한쪽에만 설치하세요(중복이면 같은 이름이 여러 곳에서 발견됩니다).
도구를 재시작해 스킬 목록을 다시 읽게 합니다.
이전 이름의 스킬(옛 프로젝트 전용)이 남아 있으면 설치기의 -Update -RetireSkill <이름>으로 정리합니다.
요청이 모호하면 스킬 설명과 맞지 않을 수 있습니다. "무엇을/어디서"를 구체화하세요.

8. 요청에 자주 붙이는 제약 문구

목적	문구
읽기 전용	"파일은 수정하지 마. 읽고 보고만 해 줘."
계획만	"구현하지 말고 plan.md 초안만 작성해 줘."
추측 금지	"컬럼/설정/ID를 추측하지 말고 확인할 수 없으면 질문해 줘."
범위 제한	"[SUP010] 관련 파일만 바꿔. 다른 화면은 건드리지 마. 범위 밖의 문제는 목록으로만 알려 줘."
비밀 보호	"설정 파일의 비밀 값은 열지 말고 출력하지 마. 키 이름만."
검증 요구	"완료를 보고하기 전에 hs_inspect, design_lint, node --check를 실행하고 출력을 붙여 줘. 실행하지 못한 검증은 '미수행 + 이유'로."
운영 보호	"운영 서버/DB에는 접속하지 마. 배포·삭제·재시작 명령은 실행하지 말고 제안만 해."
결과 형식	"표로, 근거(파일:줄)와 함께. 확신이 낮은 항목은 '추정'으로 표시."
원인 먼저	"코드를 고치기 전에 원인을 근거와 함께 확정하자. 가설은 하나씩 검증해."

1. 좋은 요청의 구성​

2. 읽기·이해 (파일을 바꾸지 않음)​

3. 만들기​

4. 고치기·진단​

5. 검증·테스트​

6. 운영·배포​

7. 스킬이 켜지지 않을 때​

8. 요청에 자주 붙이는 제약 문구​