서문

본격적인 논의에 들어가기에 앞서 솔직하게 말씀드리고 싶은 것이 있습니다. 이 글에 등장하는 프레임워크 중 그 어떤 것도 제 것이 아닙니다. 여기에 담긴 아이디어는 저보다 훨씬 더 깊고 오래 이 문제를 고민해 온 두 분으로부터 왔으며, 제가 한 마디 더 하기 전에 그분들에게 온전한 공로를 돌려야 마땅합니다.

Dan Shapiro — Glowforge의 CEO이자 Wharton 연구원이며, 이 모든 대화에 어휘를 제공한 분입니다. 그의 블로그 포스트 “The Five Levels: from Spicy Autocomplete to the Dark Factory”는 제가 하려는 모든 말의 개념적 중추입니다. 원문을 읽어보세요. 짧고 날카로우며, 가장 좋은 방식으로 당신을 불편하게 만들 것입니다. danshapiro.com

Layer 1(레이어 1)은 완료되었습니다. 8개의 이슈, 작동하는 주문 관리 API, Pact 계약(contracts), CI/CD 파이프라인, 그리고 사양 감사 프레임워크(spec audit framework)가 준비되었습니다. 사양 레이어(specification layer)는 끝났습니다.

Layer 2(레이어 2)가 여기서 시작됩니다. 그리고 생각하기 전까지는 단순해 보이는 질문 하나로 시작합니다. 왜 당신은 계속해서 똑같은 프롬프트를 다시 작성하고 있습니까?

프롬프트를 복사하는 것의 문제점

AI를 몇 주 이상 진지하게 사용해 왔다면, 당신에게는 잘 작동하는 프롬프트 모음이 있을 것입니다. 당신은 그것들을 다듬었습니다. 세션 사이에서 그것들을 복사합니다. 작업 시작 시 Claude Code에 그것들을 붙여넣으면 에이전트(agent)가 올바르게 동작합니다.

그것이 마치 시스템처럼 느껴질 것입니다. 하지만 그렇지 않습니다.

프롬프트를 복사하는 것이 실제로 하는 일은 다음과 같습니다: 단어들을 복사하는 것입니다. 계약(contract)을 복사하는 것이 아닙니다. 에이전트는 단어를 읽고, 이번 세션의 맥락(context) 안에서 이를 해석하며, 프롬프트에 명시되지 않은 일련의 결정들을 내립니다. 동일한 단어를 사용하더라도 세션이 다르면, 맥락이 다르면, 결정도 달라집니다. 두 에이전트가 동일한 프롬프트로부터 호환되지 않는 결과물을 생성하고, 당신이 어느 쪽이 맞는지 파악해야 하는 상황이 오기 전까지는 이를 알아차리지 못할 것입니다.

기술 (Skill)은 다릅니다. 기술은 단순히 무엇을 고려할지가 아니라, 무엇을 생산할지를 명시합니다. 기술은 버전, 출력 계약 (output contract), 그리고 라우팅 신호 (routing signal)를 가집니다. 기술은 시간이 지남에 따라 개선되며, 그 개선 사항은 지속됩니다. 이는 당신이 스스로에게 적어둔 메모와, 인간과 에이전트(agent)를 포함한 팀 전체가 의존할 수 있는 인프라 (infrastructure) 사이의 차이와 같습니다.

적절한 후보 찾기

프롬프트를 기술로 전환하기 위한 최적의 후보를 찾기 위해 order-api 프로젝트 전체를 검토했습니다. 세 가지 지침이 나타났습니다.

테스트 실행 검증 시퀀스 (pytest tests/steps/ -v && pytest tests/pact/ -v && python scripts/can_i_deploy.py)는 모든 세션에서 나타납니다. 탈락 — 이것은 절차 (procedure)이지, 판단 (judgment call)이 아닙니다. 어떤 에이전트라도 세 개의 명령어를 실행할 수 있습니다.

결과 파일 프로토콜 (findings file protocol)은 CLAUDE.md에 나타나며 Issue #3 이후로 준수되어 왔습니다. 탈락 — 이것은 형식과 주기 (cadence)를 설명할 뿐, 방법론 (methodology)을 설명하는 것이 아닙니다.

Gherkin 시나리오 품질 평가 — 시나리오를 수락하거나 작성하기 전에 해당 시나리오가 잘 구성되었는지 결정하는 방법론 — 가 Issue #5, #7, #8 전반에 걸쳐 나타났습니다. 매번 에이전트는 동일한 판단 프레임워크 (judgment framework)를 처음부터 다시 도출했습니다. 이것이 승자입니다.

이유: 이것은 절차가 아닌 판단을 인코딩(encode)하기 때문입니다. 특정 단계가 미지정 (UNDERSPECIFIED) 상태인지 또는 누출된 추상화 (LEAKY ABSTRACTION)인지 여부는 추론 (reasoning)의 영역입니다. 이 기술의 출력은 모든 후속 작업(downstream)을 주도합니다. 모든 구현 세션은 시나리오가 잘 구성되어 있는지에 달려 있습니다. 계획 세션에서 작성된 잘못된 시나리오는 두 세션 뒤에 깨진 단계 정의 (step definitions)가 됩니다.

그리고 여기 불편한 사실이 있습니다. Issue #8에서 수정된 타임아웃 모호성 — And the response is returned within 12 seconds — 는 사실 Issue #2에서 도입되었습니다. 세 번의 세션 동안 이것이 발견되기 전까지 조용히 상속되었습니다. Issue #2에서 품질 평가 기술이 실행되었다면, 이것이 커밋(commit)되기 전에 잡아냈을 것입니다.

프롬프트 버전 — 그리고 무엇이 잘못되었는가

다음은 세션에 붙여넣게 될 현재의 프롬프트입니다:

Gherkin 시나리오를 작성하거나 수락하기 전에, 그것이 잘 형성되었는지(well-formed) 확인하십시오. 잘 형성된 시나리오는 구현(implementation) 관점이 아닌 호출자(caller)의 관점에서 동작을 설명해야 합니다. 각 단계(step)는 오직 하나의 구현만이 이를 충족할 수 있을 정도로 충분히 구체적이어야 합니다. 다음 사항을 확인하십시오: 모호한 수량, 전체 또는 추가로 해석될 수 있는 수치, 시작 기준점(start anchor)이 없는 시간 범위, 메커니즘에 대한 설명 없이 메커니즘을 주장하는 경우, 그리고 내부 필드 이름(internal field names)이 명세(spec)로 유출되는 경우. 시나리오에 이러한 문제가 있다면, 진행하기 전에 다시 작성하십시오.

네 가지 약점:

출력 형식(output format)의 부재. 프롬프트는 에이전트가 다시 작성하거나 그대로 진행할 것임을 암시하지만, 무엇을 반환해야 하는지는 말하지 않습니다. 문제 목록인가요? 주석이 달린 버전인가요? 아니면 교정된 Gherkin인가요? 두 명의 에이전트는 서로 다른 두 가지 출력 형태(output shapes)를 생성할 것입니다. 이를 소비하는 다운스트림(downstream) 에이전트는 어떤 형태를 받든 그것을 파싱해야만 합니다.

분류 체계(taxonomy)의 부재. "내부 필드 이름"은 특정한 의미를 갖지만, 프롬프트는 무엇이 내부(internal)이고 무엇이 외부(external)인지 정의하지 않습니다. 두 에이전트는 그 경계선을 서로 다르게 긋습니다.

부분적인 문제에 대한 처리 방식 부재. "진행하기 전에 다시 작성하십시오" — 이것이 모든 단계를 다시 작성하라는 뜻인가요, 아니면 문제가 있는 단계만 다시 작성하라는 뜻인가요?

문맥 의존성(Context-dependence). 이 프롬프트는 기존 시나리오를 검토하기 위해 작성되었습니다. 이를 계획(planning) 문맥(예: "DELETE /orders/{id}에 대한 새로운 시나리오를 작성하라")에서 사용하면, 에이전트는 검토를 무시하거나 초안 작성 도중에 검토를 적용하게 됩니다. 이 두 가지 전략은 서로 다른 수준의 수정(revision)을 만들어냅니다.

근본적인 문제: 프롬프트는 무엇을 찾아야 하는지는 설명하지만, 무엇을 생성해야 하는지는 설명하지 않습니다. 에이전트가 출력 형식을 스스로 만들어냅니다. 출력 형식이 임의로 만들어질 때, 그것은 결코 두 번 같을 수 없습니다.

데모 (The demonstration)

동일한 입력. 동일한 엔드포인트(endpoint). 첫 번째는 프롬프트 버전, 두 번째는 기술(skill) 버전입니다.

작업: DELETE /orders/{order_id} — 확인된 주문을 취소하는 Gherkin 시나리오를 작성하십시오. 주문은 결제가 아직 캡처(captured)되지 않은 경우에만 취소할 수 있습니다.

작업 A — 프롬프트 버전 출력:

시나리오: 결제 캡처(payment capture) 전 확정된 주문 취소
  Given 주문 ID "order-123"를 가진 확정된 주문이 존재함
  And 해당 주문에 대한 결제가 캡처(captured)되지 않음
...

에이전트가 프롬프트에 명시되지 않았음에도 내린 6가지 암묵적 결정 사항:

1. "확정된 주문이 존재함(confirmed order exists)" — 설정 방법이 지정되지 않음. 직접 시드(seed)를 생성할 것인가, 아니면 POST /orders를 호출할 것인가? 열려 있는 상태로 남겨둠.
2. "결제가 캡처되지 않음(payment has not been captured)" — 메커니즘이 지정되지 않음. 모의(Mock) 서버 상태인가? 주문의 플래그(flag)인가?
3. "주문이 취소됨(the order is cancelled)" — 메커니즘 언어. 어떤 필드가 변경되는가? 어떤 값으로 변경되는가? 지정되지 않음.
4. "확인 메시지(confirmation message)" — 어떤 필드에든 어떤 텍스트가 있으면 이를 만족함. 정의되지 않음.
5. 200 vs 204 — 에이전트는 204(본문 없음) 대신 200을 선택함. 문서화되지 않은 판단.
6. 실패 시나리오 없음(No failure scenario) — 프롬프트는 "결제가 아직 캡처되지 않은 경우에만 취소할 수 있다"라고 언급했지만, 에이전트는 성공 케이스만 작성함.

총 암묵적 결정 사항: 6개. 모두 무음(silent)으로 처리됨.

작업 B — 스킬(skill) 버전 출력:

시나리오: 결제가 아직 캡처되지 않았을 때 확정된 주문이 취소됨
  Given POST /orders를 통해 주문 ID "order-del-001" 및 상태 "CONFIRMED"로 주문이 생성됨
  And 결제 게이트웨이가 주문 "order-del-001"에 대한 결제를 캡처하지 않음
...

두 가지 암묵적 결정 사항 — 둘 다 명시적으로 드러남:

1. 422 vs 409 — 스킬의 출력 계약(output contract)은 가정을 문서화할 것을 요구하므로, 이는 암묵적으로 포함되는 대신 주석으로 표시됨.
2. "status" vs "cancellation_status" — 스킬의 누수된 추상화(LEAKY ABSTRACTION) 체크가 구현 중심적인 필드 이름을 사용하는 것을 방지함.

총 암묵적 결정 사항: 2개. 모두 가시적(visible)임.

차이점(The diff)

여섯 가지 유의미한 차이점. 세 가지 스킬 제약 조건, 세 가지 품질 차이, 그리고 여섯 가지 프롬프트의 모호성이 제거됨.

프롬프트에는 없고 스킬에는 있는 세 가지 속성

1. 버전 관리 (Version control)

프롬프트에는 버전이 없습니다. 프롬프트를 개선할 때, 당신은 새로운 텍스트를 다음 세션에 복사할 뿐입니다. 이전 버전은 클립보드 기록이나 3주 전의 채팅 기록 속에 존재합니다. 당신은 이를 디프(diff)할 수 없습니다. 특정 세션을 프롬프트에 고정(pin)할 수도 없습니다. 잘 작동했던 프롬프트와 잘못된 출력을 생성한 프롬프트 사이에 무엇이 변했는지 확인할 수도 없습니다.

Gherkin 품질 스킬은 docs/skills/gherkin-scenario-quality.md에 존재합니다. Issue #8에서 IMPLICIT FLOW 부채 클래스가 추가되었을 때, 스킬은 다음과 같이 한 줄 업데이트되었습니다.

+| IMPLICIT FLOW | 어디에도 명시되지 않은 후속 흐름을 암시하는 단계 |

해당 커밋 이후의 모든 세션은 업데이트된 스킬을 사용합니다. 그 이전의 모든 세션은 이전 버전을 사용했습니다. git blame은 IMPLICIT FLOW가 정확히 언제 추가되었는지, 어떤 이슈가 이를 유도했는지 알려줍니다. 프롬프트의 경우, "스킬 v1.1"이라는 말은 아무런 의미가 없습니다. 오직 "오늘 내가 사용 중인 프롬프트"가 있을 뿐입니다.

2. 출력 계약 (Output contract)

스킬은 무엇을 반환해야 하는지 정확하게 명시합니다:

• Given/When/Then 형식의 하나 이상의 완전한 Gherkin 시나리오
• 모든 Then 절은 단순히 존재 여부가 아니라, 필드 이름과 값을 모두 단언(assert)해야 함
• 모든 수치는 "정확히 N번(exactly N)" 또는 "총 N개 이하(no more than N total)"를 사용해야 하며, 결코 "N번(N times)"이라고 표현해서는 안 됨
• 모든 시간 범위(time bounds)는 시작 앵커(start anchor)를 포함해야 함
• Given 절의 각 외부 서비스는 명시적으로 이름이 지정되어야 함
• 입력에 없는 가정 사항은 # Assumption: 주석으로 나타나야 함

하위 의존성(downstream dependency)은 단계 정의(step definition) 작성자입니다. tests/steps/test_order_creation.py가 And the payment gateway received exactly one charge request를 구현할 때, "exactly one", "charge request", "payment gateway"는 모두 실행 가능한(actionable) 정보입니다. 반면 "And the response includes a confirmation message"를 구현할 때, 작성자는 단언(assertion)을 스스로 만들어내야 합니다. 그 임의적인 작성이 바로 테스트 커버리지가 신뢰할 수 없게 되는 지점입니다.

출력 계약은 시나리오를 작성하는 에이전트와 이를 바탕으로 구현하는 에이전트 사이의 인터페이스입니다.

3. 라우팅 신호 설명 (Routing signal description)

스킬의 설명 라인:

스킬의 설명 라인:

order-api 프로젝트를 위해 5가지 질문 부채 진단(five-question debt diagnostic)을 사용하여 잘 구성된 Gherkin 시나리오를 평가하고 생성합니다.

이는 아티팩트 유형, 프로젝트, 메서드, 그리고 출력을 명시합니다. 에이전트는 이 스킬을 언제 사용해야 할지, 그리고 무엇을 받을 수 있는지 정확히 알고 있습니다.

동일한 스킬에 대한 잘못된 설명:

프로젝트의 테스트 작성 및 시나리오 확인에 도움을 줍니다.

'테스트(Tests)'는 pytest, Pact 계약, 단위 테스트, Gherkin과 일치합니다. '프로젝트(The project)'는 모든 레포지토리와 일치합니다. 방법론이 명시되지 않았다는 것은 '테스트 작성에 도움을 주는' 두 에이전트가 호환되지 않는 출력을 생성한다는 의미이며, 이는 스킬이 존재하여 해결하려는 바로 그 문제입니다.

답변

프롬프트와 스킬 모두 작동하는 출력을 생성한다 하더라도 차이점은 이렇습니다:

프롬프트는 오늘날의 테스트를 통과하는 출력을 생성합니다. 반면, 스킬은 다른 에이전트가 당신이 내린 결정을 변경하지 않고도 내일 구현할 수 있는 출력을 생성합니다.

그래서 프롬프트를 복사하는 것만으로는 충분하지 않습니다. 단어는 이동하지만, 계약(contract)은 그렇지 않습니다.

다음 이슈: 실제 적용에서의 3계층 스킬 아키텍처 — 당신의 스킬을 올바른 계층에 매핑하고 왜 Tier 2가 개별 전문성이 조직적 레버리지(organizational leverage)가 되는 곳인지.

출처 및 추가 자료

• Nate B. Jones —
  · natebjones.com
• Dan Shapiro — The Five Levels: from Spicy Autocomplete to the Dark Factory
• 프로젝트 레포지토리
• Gherkin 품질 스킬
• 세션 결과 — 이슈 #9

이 글은 AI 도구의 도움을 받아 작성되었습니다.