예시가 지시보다 강할 때가 있다

2026.07.09 게시

이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.

예시가 지시보다 강할 때가 있다

신규 기능 개발을 시작할 때마다 SDD 문서를 만든다.

as-is 분석하고, to-be 매핑하고, change plan 만들고, backlog로 쪼개는 식이다.

처음에는 매번 Agent에게 폴더 구조를 설명했다.

docs/{feature}-sdd/
  README.md
  01-as-is-flow.md
  change-plans/
  backlog/
  implementation-backlog.md

처음엔 이 정도는 그냥 프롬프트로 매번 설명하면 된다고 생각했다.

그런데 몇 번 해보니 귀찮은 게 문제가 아니었다.

진짜 문제는 매번 결과가 조금씩 달라진다는 거였다.

어떤 날은 README에 링크가 잘 들어가고, 어떤 날은 빠졌다. 어떤 날은 아직 만들지도 않은 파일을 후속 문서로 미리 박아버렸다. 어떤 날은 TODO 문구가 이상하게 구체적이었다.

내가 원한 건 대단한 게 아니었다.

신규 작업을 시작할 때 SDD 문서 뼈대만 항상 같은 형태로 만들고 싶다.

그래서 sdd-doc-scaffold라는 skill을 만들었다.

Skill은 매크로가 아니었다

처음엔 skill을 매크로처럼 생각했다.

sdd scaffold 만들어줘라고 하면 정해진 파일을 그대로 찍어내는 기능이라고 생각했다.

그런데 써보니 아니었다.

skill은 실행되는 프로그램이 아니라, Agent가 필요할 때 읽는 문서에 가깝다. 평상시에는 description만 올라가 있고, 요청이 맞물려지면 본문이 컨텍스트로 들어간다.

이게 생각보다 중요하다.

읽힌다는 건, Agent가 그 내용을 해석한다는 뜻이다.

지시가 애매하면 애매하게 해석한다. 지시끼리 충돌하면 임의로 택한다. 예시가 있으면 예시에 끌려간다.

흐름으로 보면 대충 이렇다.

사용자 요청
  → Skill description 매칭
  → Skill 본문이 컨텍스트로 들어옴
  → Agent가 지시와 예시를 해석
        ├ (애매한 지시) → 모델별 해석 차이
        └ (강한 예시)   → 예시 복사
  → 파일 생성 결과

이번 실험은 그걸 확인한 기록이다.

실험은 이렇게 했다

같은 sdd-doc-scaffold skill을 Claude Code와 Codex에 각각 적용했다.

목표는 Stage 1 산출물 두 개를 같은 형태로 만드는 것이었다.

docs/{feature}-sdd/
  README.md
  01-as-is-flow.md

Claude Code에는 이렇게 요청했다.

/sdd-doc-scaffold sample-claude-rest-api 생성해줘
진입 포인트는 src\main\java\...\controller\SampleFeatureController.java

Codex에는, 1차에는 이렇게 요청했다.

$sdd-doc-scaffold sample-codex-rest-api 생성해줘. 진입점: src\main\java\...\controller\SampleFeatureController.java

그러자 Codex가 domain 문서 경로를 되물었다.

내가 경로를 답해줬고, 2차부터는 그 값을 처음부터 프롬프트에 넣었다.

$sdd-doc-scaffold sample-codex-rest-api 생성해줘.
- 작업 ID prefix: SAMPLE-CODEX-REST-API
- as-is 진입점: src\main\java\...\controller\SampleFeatureController.java
- domain 문서 경로: src\main\java\...\feature\domain

여기서 이미 문제가 씨앗을 품고 있었다.

Claude와 Codex의 프롬프트가 같지 않았고, Codex 쪽은 회차 간에도 달랐다.

그리고 이 차이는 내가 실수로 다르게 친 게 아니었다.

1차에서 Codex가 되물었고, 내가 답해준 값이 다음 프롬프트에 들어간 것이다.

즉, 프롬프트 차이는 상호작용 이력에서 자라났다.

당시에는 별생각이 없이 넘겼는데, 나중에 비교할 때 이 차이가 발목을 잡았다.

비교 기준은 다음으로 잡았다.

  • 파일 이름
  • 섹션 구조
  • 문서 관계 블록
  • TODO 문구
  • README의 후속 문서 링크
  • 관련 코드 경로 표기

먼저 실험 조건부터 적어둔다

정직하게 말하면 이건 엄밀한 실험은 아니다.

  • 각 조건은 1회씩만 돌렸다. n=1이다.
  • 1차, 2차에 사용한 skill 원문은 남아 있지 않다. 같은 파일을 계속 덮어썼다.
  • 그래서 이 글에서 v1.x의 문구를 인용한 부분은 전부 대화 기록을 보고 재구성한 것이다. 정확한 문장은 다를 수 있고, 취지 기준으로 봐야 한다.
  • 2차 Codex는 1차와 같은 폴더에 덮어썼다. 즉, 자기 1차 산출물을 읽을 수 있는 상태였다.
  • 프롬프트는 Claude와 Codex가 서로 달랐고, Codex는 1차와 2·3차가 달랐다. 경합은 있을 수 있다.
  • 3차 직전에는 조사 금지, TODO 원문화, 섹션 예시, 선행/후속 고정화를 한꺼번에 바꿨다.
  • 그래서 “TODO 원문화 하나 때문에 좋아졌다”고 단정할 수는 없다.

버전과 회차는 헷갈리기 쉬우니 표로 정리하면 이렇다.

실험 사용한 skill
1차 v1.x
2차 v1.x
3차 v2
실험 유효 v2-fix

v2-fix는 3차 결과를 보고 만든 버전이다.

3차에 쓴 게 아니다.

그리고 아직 한 번도 실행하지 않았다.

이유는 다음에 적는다.

1·2차: 구조는 맞는데 내용이 흔들렸다

먼저 잘 된 부분부터 보면, 파일 구성과 섹션 구조는 4개 산출물 모두 동일했다.

이건 꽤 의미가 있었다.

적어도 skill을 쓰면 “어떤 파일을 만들지”, “어떤 섹션을 둘지” 정도는 안정됐다.

문제는 그 안에 들어가는 값이었다.

특히 TODO 문구가 흔들렸다.

# Claude 1차
> TODO: `.../feature/domain/` (md 14종). 상태: 미커밋(working tree, 기준 커밋 b580bb53 이후). 링크는 걸지 않는다.

# Codex 1차
> TODO: `.../feature/domain/` + 마지막 갱신 커밋 요약(Git 미추적).

같은 TODO인데 문장이 다르다.

Claude 1차와 2차도 서로 달랐다.

같은 엔진, 같은 명령인데도 결과가 조금씩 달랐다.

처음엔 그냥 “TODO 문구가 비결정적이구나” 정도로 생각했다.

그런데 다시 보니 더 이상한 게 있었다.

“md 14종”은 어디서 나온 숫자인가.

나는 뼈대만 만들라고 했다.

그런데 Agent가 domain 폴더를 열어서 파일을 센 것처럼 적어뒀다.

그리고 틀렸다.

실제로는 15개였다.

아마 제대로 센 것도 아니었을 것이다. 대충 보고 어림한 것에 가깝다.

문제는 그 어림값이 문서에 사실처럼 박혔다는 점이다.

문서가 오래돼서 틀린 게 아니다.

처음 작성할 때부터 틀렸다.

원인은 skill 안에 있었다

나중에 보니 원인은 Agent가 아니라 skill 안에 있었다.

v1.x 규칙에는 이런 취지의 문장이 있었다. (원문은 남아 있지 않아 재구성이다.)

내용을 추측해서 채우지 않는다.

그런데 입력 항목에는 또 이렇게 적혀 있었다.

기존 domain 문서 유무 + 마지막 갱신 커밋을 확인한다.
없으면 git rev-parse로 얻는다.

한 파일 안에서 두 지시가 싸우고 있었다.

  • 추측하지 마라.
  • 그런데 domain 문서 유무와 git 상태는 확인하라.

이걸 그림으로 보면 이렇다.

skill.md
  ├ "내용을 추측해서 채우지 않는다"
  └ "domain 문서 유무와 git 상태를 확인한다"
        │  (두 지시가 충돌)
        ▼
   Agent 해석 ─┬→ TODO로 남김
              ├→ 사용자에게 되물음
              ├→ 직접 조사함
              └→ 조사한 척 채움 → "md 14종" 같은 틀린 값 발생

Agent 입장에서는 둘 다 지시다.

그래서 어떤 날은 조사하고, 어떤 날은 TODO로 남기고, 어떤 날은 조사한 척하면서 틀린 값을 적었다.

이 편차는 엔진 개성만 가린 게 아니었다.

1차 Codex를 다시 보면, 같은 회차 안에서도 값마다 처리가 달랐다.

domain 경로는 대놓고 되물었다. git 상태는 묻지 않고 채웠다.

같은 엔진이, 같은 skill을 읽고, 한 값은 묻고 한 값은 임의로 처리했다.

Claude는 둘 다 묻지 않고 조사했고, 그중 하나는 틀렸다.

이건 단순히 “Agent가 자유로워서 결과가 흔들린다”의 문제가 아니었다.

비워둘지, 조사할지, 물어볼지 자체가 skill 안에서 모순되고 있었다.

v2에서는 모순을 없앴다

그래서 v2에서는 방향을 바꿨다.

scaffold 단계에서는 아무것도 조사하지 않게 했다.

4. 아무것도 조사하지 않는다.
   코드, 파일 목록, git 로그를 읽지 않는다. 파일 개수를 세지 않는다.
   필요한 값은 전부 사용자가 인자로 준다.
   인자로 받지 못한 값은 조사하지 말고 되묻는다.

5. TODO 문구는 예시다.
   아래 템플릿의 > TODO: 네 문장은 한 글자도 바꾸지 않고 그대로 복사한다.

입력 항목도 줄였다.

  • feature 슬러그
  • 작업 ID prefix
  • 관련 코드 경로
  • 기준 커밋
  • 작성일

domain 문서 유무나 git 상태는 scaffold 단계에서 확인하지 않게 했다.

이때 기준이 하나 잡혔다.

scaffold의 목적은 정보를 알아내는 게 아니다.

정보를 채울 자리를 안정적으로 만드는 것이다.

조사와 분석은 후속 skill인 sdd-as-is-analyze가 할 일이다.

뼈대를 만드는 단계에서 관련 코드를 열고, 파일을 세고, git을 뒤지기 시작하면 scaffold가 scaffold가 아니게 된다.

3차: 되묻기가 일관돼졌다

v2를 적용한 3차에서는 01-as-is-flow.md 본문이 글자 단위로 일치했다.

특히 아래 TODO 문구는 그대로 들어갔다.

## 참고한 domain 문서

> TODO: 경로와 마지막 갱신 커밋. 없으면 "없음". 링크는 걸지 않는다.

## 확인 못 한 것

> TODO: 코드만 봐선 판단 불가한 항목. 비워두지 말고 "없음"이라도 적는다.

그리고 더 중요한 변화가 있었다.

두 프롬프트 어디에도 기준 커밋을 주지 않았다.

skill에는 이렇게 적어뒀다.

기준 커밋 - as-is 문서에 받아 적어. 사용자가 주지 않으면 묻는다.

3차에서는 두 Agent 모두 기준 커밋을 물어봤다.

내가 b580bb53을 답했고, 산출물에도 같은 값이 들어갔다.

정확히 하자면, 되묻기 자체가 v2에서 처음 나온 동작은 아니다.

Codex는 v1.x인 1차에서도 domain 경로를 물어봤다.

하지만 그건 일관된 동작이 아니었다.

같은 1차에서 Codex는 git 상태를 묻지 않고 채웠고, Claude는 아무것도 묻지 않고 파일을 세다가 틀렸다.

v2가 바꾼 건 되묻기의 유무가 아니라 일관성이다.

무엇을 묻고 무엇을 묻지 않았는지가, 엔진과 회차와 상관없이 고정된다.

이 차이가 꽤 크다.

모르는 값을 임의로 채우는 Agent보다, 모르는 값을 모른다고 보고 물어보는 Agent가 훨씬 다루기 쉽다.

그리고 그 둘을 가른 건 Agent의 성격이 아니라 skill의 일관성이었다.

그런데 README에는 아직 차이가 남았다

3차도 README에는 차이가 있었다.

처음에는 “아직도 흔들리는 부분이 있네”라고 봤다.

그런데 하나씩 뜯어보니 세 차이가 전부 같은 성격은 아니었다.

차이 Claude Codex
관련 코드 controller 1개, / controller + domain 2개, \, <br>
문서 종류 as-is README
작성일 행 있음 없음

1. 관련 코드 차이는 차이가 아니었다

프롬프트를 다시 보면 답이 나온다.

Codex에만 domain 문서 경로를 줬다.

- domain 문서 경로: src\main\java\...\feature\domain

그리고 이 줄이 어디서 왔는지도 앞에서 봤다.

1차에서 Codex가 되물어서 생긴 줄이다.

그러니 Codex가 controller와 domain 경로 두 개를 적은 건 이상한 게 아니었다.

받은 값을 그대로 적은 것이다.

처음 비교할 때 나는 이걸 “Codex가 조사해서 채웠다”고 판단했다.

틀린 해석이었다.

내가 입력을 다르게 줬고, Codex는 그 차이를 출력에 반영했을 뿐이다.

출력 diff만 보면 이런 실수를 하기 쉽다.

비교를 하려면 먼저 입력부터 통제해야 한다.

특히 이번처럼 되묻기에 답해준 값이 다음 프롬프트에 섞이는 구조라면, 입력은 가만히 둬도 회차마다 달라진다.

이걸 놓치고 결과만 보면, 정직한 쪽이 오히려 틀렸다고 판단할 수 있다.

2. 사람인 나도 다시 보니 판단이 꼬였다

경로 표기도 달랐다.

  • Claude: /
  • Codex: \

프롬프트는 양쪽 다 \ 역슬래시로 줬다.

즉, v2 규칙 기준으로 보면 Codex가 더 정확하다.

Codex는 사용자가 준 문자열을 유지했고, Claude는 /로 바꿨다.

그런데 나는 나중에 skill을 고치면서 경로 표기를 / 고정으로 바꿨다.

결과만 보면 좀 웃긴 상황이다.

규칙을 지킨 쪽이 틀렸다고 보고, 규칙을 어긴 쪽의 결과에 맞춰 skill을 바꾼 셈이다.

물론 최종적으로 문서의 경로 표기를 /로 통일하는 방향은 맞다고 본다.

Markdown 문서에서 Java 경로를 적을 때는 /가 읽기 편하고, OS 차이도 덜 탄다.

하지만 순서는 구분해야 한다.

Claude가 맞아서 /로 바꾼 게 아니다.

내 규칙이 부실해서 /로 고정하는 규칙을 새로 추가한 것이다.

이 순서를 헷갈리면 다음번에는 엉뚱한 걸 고치게 된다.

3. 진짜 문제는 문서 종류와 작성일이었다

v2 skill에는 이런 블록이 있었다.

## 문서 관계 블록 (모든 문서 필수)

**아래는 표현 예시가 아니라 채워질 실제 예시다.**

| 항목      | 값                                                     |
| --------- | ------------------------------------------------------ |
| 문서 종류 | as-is                                                  |
| feature   | sample-api                                             |
| 작업 ID   | 해당 작업                                              |
| 선행 문서 | 없음                                                   |
| 후속 문서 | 미정                                                   |
| 관련 코드 | `src/main/java/com/example/feature/SampleService.java` |
| 기준 커밋 | `abc1234`                                              |
| 작성일    | 2026-07-09                                             |

그리고 아래에는 이런 규칙이 붙었다.

- 문서 종류: 해당 문서의 종류 하나만 적는다.
- 기준 커밋 / 작성일: as-is 계열만. 다른 문서에서는 두 행을 뺀다.

README 템플릿에는 이렇게 적혀 있었다.

# {feature} SDD

[문서 관계 블록]

문제는 [문서 관계 블록]이라는 간접 참조였다.

Agent는 README 템플릿에서 [문서 관계 블록]을 보고 위쪽 예시 표를 찾아갔다.

그런데 그 예시 표는 as-is 문서 기준으로 채워져 있었다.

Claude 3차 README에는 결국 이렇게 들어갔다.

문서 종류 | as-is
작성일 | 2026-07-09

README인데 문서 종류가 as-is로 들어갔다.

README에는 없어야 할 작성일 행도 들어갔다.

규칙 원문은 “README에는 빼라”는 뜻으로 적혀 있었다.

하지만 Claude는 예시 표를 더 강하게 봤다.

반대로 Codex는 규칙 원문을 따랐다.

README의 문서 종류는 README로 들어가고, 작성일 행은 빠졌다.

같은 skill을 줬는데 한쪽은 예시를 읽고, 한쪽은 규칙을 읽은 셈이다.

그리고 예시가 틀려 있었다.

예시는 생각보다 강하다

이 skill을 고치면서 같은 문제를 여러 번 봤다.

예상한 것 실제로 나온 것
as-is / to-be / change-plan 선택지 나열 선택지 문자열이 값으로 들어감
채워질 실제 값 as-is 그 값이 그대로 복사됨
[문서 관계 블록] 간접 참조 참조 대상 표가 통째로 복사됨

선택지를 두면 선택지를 복사한다.

값을 두면 값을 복사한다.

참조를 두면 참조 대상을 복사한다.

처음에는 “선택지를 그대로 쓰지 마라” 같은 지시를 더 쓰면 해결될 줄 알았다.

그런데 이미 그런 지시는 skill 안에 있었다.

그래도 복사됐다.

뜯어보면 예시 위에 내가 붙인 문장부터가 문제일 수 있었다.

“아래는 표현 예시가 아니라 채워질 실제 예시다.”

예시의 무게를 줄여주려고 쓴 문장인데, Agent 입장에서는 “이 값이 정답”이라고 읽었을 수도 있다.

그러나 이건 지시문을 더 늘려서 해결할 문제가 아니었다.

복사할 대상이 없거나, 복사라는 말도 없어야 한다.

다만 예시가 항상 이기는 건 아니다.

같은 예시 표에는 후속 문서 | 미정도 있었다.

그런데 Claude 3차 README에는 후속 문서가 [01-as-is-flow.md](./01-as-is-flow.md)로 제대로 들어갔다.

이건 skill에 따로 둔 선행/후속 고정 규칙을 따른 것이다.

2차에는 이 값이 미정으로 나왔었다.

즉, 같은 표 안에서도 어떤 행은 복사되고, 어떤 행은 규칙을 따른다.

그래서 정확히 말하면 이렇다.

예시가 항상 지시를 이기는 건 아니다. 하지만 자주 이긴다.

그리고 skill을 만들 때는 그 정도면 충분히 위험하다.

v2-fix는 만들었지만 실행하지 않았다

남은 차이를 다 뜯어보니 고칠 방향은 명확했다.

그래서 v2-fix에서는 이렇게 바꿨다.

  • 공통 예시 표를 삭제했다.
  • README / 01 템플릿의 관계 표를 각각 펼쳐서 넣었다.
  • 치환 자리는 {feature}, {관련코드}, {기준커밋}, {작성일}처럼 정확히 적었다.
  • README 표에는 기준 커밋, 작성일 행을 애초에 넣지 않았다.
  • “이 행은 빼라”고 쓰는 대신, 처음부터 빠진 표를 줬다.
  • 경로 표기는 /로 고정했다.

그리고 4차를 돌리려다가 멈췄다.

남은 차이가 실제로 뒤 단계를 망가뜨리는지 봤다.

단순 차이 실제 영향
관련 코드 경로 개수·서식 없음. 채우는 단계에서 갱신됨
README 문서 종류 오기재 있음. 이 값으로 분기하는 곳이 있음
README 작성일 행 유무 없음

전부 실제 영향이 있었던 건 아니다.

애초에 풀려던 문제는 문서 간 링크 부재였다.

전 세션의 Agent가 어디서부터 봐야 하는지 몰라서 헤매는 문제.

그건 이미 해결됐다.

README가 진입점이 되고, 관계 블록과 선행/후속 링크가 들어간다.

남은 차이는 기능 구현을 망가뜨리지 않았다.

그럼 거기에 멈추는 게 맞다고 봤다.

남은 차이가 하나도 없어질 때까지 계속 고칠 수도 있다.

그런데 그게 다음 세션의 작업 성공에 영향을 주지 않는다면, 그건 그냥 정리 취미에 가깝다.

그래서 v2-fix는 고쳤지만 검증하지 않은 상태로 남겨둔다.

나중에 이 skill을 다시 쓸 일이 생기면 그때 같이 확인하면 된다.

정리

처음 목표는 소박했다.

skill로 SDD 문서 뼈대를 매번 같은 형태로 만드는 것. 템플릿 하나 고정하는 일이었다.

그런데 하다 보니 일이 커졌다.

뼈대를 고정하려다 skill 안의 지시 충돌을 찾았고, 예시가 복사되는 문제를 찾았고, 마지막에는 내 비교 방법의 허점까지 찾았다.

그래도 확인한 건 단순하다.

skill을 쓰면 파일 구성이나 섹션 구조 같은 큰 틀은 꽤 잘 고정된다.

다만 skill이 매크로처럼 그대로 실행되는 건 아니었다. Agent가 문서를 읽고 해석하기 때문에, 지시가 애매하거나 예시가 강하면 결과가 흔들릴 수 있다.

특히 이번에는 두 가지가 컸다.

하나는 skill 안의 지시가 서로 충돌한다는 점이었다. “추측하지 마라”고 해놓고, 동시에 “git 상태를 확인하라”고 적어두니 처리가 갈렸다. 엔진 개성만 가린 게 아니라, 같은 엔진이 같은 회차 안에서도 어떤 값은 묻고 어떤 값은 임의로 채웠다.

다른 하나는 예시였다. 예시 표에 실제 값처럼 적어둔 내용이 그대로 복사되기도 했다. “이건 예시일 뿐”이라고 적어도, Agent가 항상 그렇게 받아들이지는 않았다.

그리고 부수적으로 하나 더 배웠다.

비교 실험을 하려면 입력부터 통제해야 한다. 이번에는 1차의 되묻기에 답해준 값이 그대로 프롬프트 차이가 되고, 그 차이를 헛짚으면 “Codex가 조사해서 채웠다”는 오해로 이어질 뻔했다.

그래서 scaffold 단계에서는 가능하면 단순하게 두는 게 낫다.

조사하지 않는다. 추측하지 않는다. 필요한 값이 없으면 묻는다. 예시는 복사돼도 문제가 없는 형태로 둔다.

이 정도만 지켜도 처음에 원하던 문제는 거의 해결된다.

README가 진입점이 되고, 문서 간 링크가 고정되고, 다음 세션의 Agent가 어디서부터 봐야 할지 알게 된다.

남은 차이는 있었지만, 실제 뒤 단계를 망가뜨리는 수준은 아니었다.

그래서 4차 실행은 돌리지 않았다.

이번에는 여기서 멈추는 게 맞다고 봤다.


관련 글

Skill의 구조와 트리거부터 처음 하나를 만드는 과정까지 정리한 입문 글이다.

Link - 매번 붙여넣던 지시를 폴더 하나로 — Agent Skill 입문

이 Skill을 Trigger·Non-trigger·Procedure로 나눠 검증한 후속 실험 기록이다.

Link - Skill 검증을 위한 Eval, 직접 돌려보았다