Prompt Engineering

한눈에 보기

Prompt Engineering은 더 좋은 문장을 쓰는 요령이 아니라, AI agent가 작업 중 지켜야 할 판단 체계를 설계하는 일입니다. KeystoneHub에서는 프롬프트, 규칙 우선순위, 신뢰도 레이블, 차단 사유가 하나의 운영 계약처럼 동작합니다.

• 핵심 질문: AI 답변과 실행을 어떻게 더 검증 가능하고 덜 임의적으로 만들 것인가?
• 읽는 대상: CLAUDE.md, 규칙 우선순위, 답변 신뢰도 체계를 이해하려는 사람
• 연결 문서: Philosophy & Direction, Harness — Hooks & Gates, Commands & Guardrails

이 문서에서 확인할 것

• 보안, git, lifecycle 규칙이 충돌할 때의 우선순위
• 검증/추론/모름을 분리하는 신뢰도 레이블
• 반복 루프에서 중간 질문을 줄이고 수렴까지 실행하는 방식

CLAUDE.md 설계 철학

CLAUDE.md는 단순한 “지시문”이 아니라 AI 에이전트의 운영 체계입니다. ai-rules의 core 13파일(3,175줄)이 모든 프로젝트에 공통 적용됩니다.

규칙 우선순위 (충돌 시)

1. 03-security  — 보안은 무조건 최우선
2. 01-git       — 되돌리기 불가 작업 (push, merge)
3. 04-lifecycle  — Plan Mode, 사람 승인 게이트
4. 나머지 규칙

신뢰도 레이블 (모든 답변 필수)

AI가 답변할 때 얼마나 확실한지 명시해야 합니다:

레이블	의미	예시
[검증됨]	코드/실행 결과로 직접 확인	빌드 성공, 테스트 통과
[추론]	파일 읽고 분석했지만 실행 미확인	코드 리뷰, 구조 분석
[모름:확인불가]	확인 수단이 없음	런타임 동작, 외부 API
[모름:정책제한]	정책·보안상 접근 제한	.env 내용
[모름:불확실]	정보가 있으나 신뢰 어려움	오래된 문서 참조

Convergence Loop — 중간 질문 금지

핵심 원칙: 반복 검증/수정 루프에서 사용자에게 “계속할까요?” 묻는 것은 금지.

❌ 금지 패턴:
  "3차 완료 — CRITICAL 2개 발견. 계속 진행할까요?"
  "전략 5개 시도 실패. 다른 방법 시도해볼까요?"
  "준비 완료" / "다음 턴에 이어집니다"

✅ 올바른 패턴:
  "3차 완료 — CRITICAL 2개 발견, 수정 후 4차 진행"
  → 바로 다음 Bash 호출 실행

종료 조건은 오직 3가지:

1. 수렴 (CRITICAL = 0)
2. EXHAUSTED (모든 전략 소진)
3. 사용자가 명시적으로 “중단”

변명 방지 테이블

AI가 흔히 하는 변명과 올바른 행동을 명시합니다:

에이전트 변명	올바른 행동
”간단한 수정이라 Plan Mode 불필요”	Plan Mode 필수 실행
”R2지만 사용자가 요청했으니 바로 실행”	확인 문구 재입력 후 실행
”@ts-ignore 한 줄이면 해결”	에러 원인을 수정하여 통과
”테스트 실패 → 테스트 수정”	코드를 수정하여 테스트 통과
”bash에서 불가능”	중간 파일 패턴으로 우회 시도
”애매해서 사용자에게 확인”	Read/Grep으로 근거 확보 후 추천안 제시

프롬프트 강화 메커니즘

prompt-enhancer.sh (UserPromptSubmit hook)

prompts3.com의 2,642개 실제 프롬프트를 분석한 RAG 기반 강화:

• 사용자 입력을 구조화된 형태로 자동 변환
• JSON Args 원칙 적용
• 매 프롬프트 입력 시 자동 실행

차단 이유 3분류

AI가 “못 한다”고 말할 때 왜 못 하는지 명시해야 합니다:

분류	뜻	예시
[차단:위험]	R2 비가역 — 데이터 영구 변경	DROP TABLE, force-push
[차단:판단근거]	안전하지만 사람만 아는 정보 필요	신규 프로젝트 여부
[차단:권한]	에이전트 접근 불가	.env 수정, OS keychain