Molayo

© 2026 Molayo

Zenn헤드라인2026. 05. 28. 10:53

Codex가 SKILL.md를 220행에서 끊는 원인은 Codex 자체 prompt의 1행이었다

요약

Codex CLI가 SKILL.md 파일을 중간에 끊어서 읽는 현상의 원인이 내부 프롬프트의 'Read only enough to follow the workflow'라는 지시문임이 밝혀졌습니다. 모델마다 이 지시를 해석하는 기준이 달라 읽기 제한 행수가 달라지며, 현재 관련 이슈가 오픈되어 있으나 수정되지 않은 상태입니다.

핵심 포인트

  • Codex CLI 내부 프롬프트의 지시문이 파일 읽기 제한의 직접적 원인
  • 모델별(gpt-5.5, 5.4 등)로 'enough'에 대한 해석 차이 발생
  • 최신 버전(v0.134.0)에서도 해당 프롬프트는 수정되지 않고 유지됨
  • OpenAI의 폐쇄적인 PR 정책으로 인해 외부 패치 적용이 지연 중

이전 기사에서 Codex CLI가 SKILL.md를 220행에서 중단하는 현상을 측정했다. "model이 학습 데이터에서 가져온 익숙한 길이의 SKILL.md"를 원인으로 추측했으나, 이는 절반만 맞았다.

진짜 원인은 Codex CLI 자신의 prompt에 "Read only enough to follow the workflow"라고 적혀 있다는 것이었다. openai/codex에 이미 Issue가 생성되었고, proposed patch까지 준비되어 있다. 지금도 그대로 남아 있다.

원인이 되는 1행

Codex CLI v0.128.0의 codex-rs/core-skills/src/render.rs를 읽어보면, skill 실행 시 model에게 전달되는 prompt 안에 이것이 포함되어 있다.

// codex-rs/core-skills/src/render.rs
pub const SKILLS_HOW_TO_USE_WITH_ABSOLUTE_PATHS: &str = r###"
- How to use a skill (progressive disclosure):
...

"Read only enough to follow the workflow" ── 이것뿐이다. skill 본문을 "partial(부분적)하게만 읽으라"고 명시하고 있다. 나의 Codex 세션 로그를 grep 해보니, 이 문자열이 대화에 그대로 포함되어 있었다. runtime에 전달되는 말 그대로의 지시다.

model은 그 "enough"를 자신의 prior(사전 지식)에 따라 서로 다른 숫자로 해석한다. 지난번에 관측한 cap(한계치)의 편차는 gpt-5.5에서 220, gpt-5.4에서 260 ── 각각의 model이 생각하는 "enough"였다.

최신 버전에서 수정되었는가

최신 release는 **v0.134.0 (2026-05-26 공개)**로, 내가 측정한 시점으로부터 6 versions 진행되었다. rust-v0.128.0과 rust-v0.134.0에서 render.rs를 diff 해보면, 변경 사항은 plugin_id: None,이라는 1행 추가 (skill analytics 용)뿐이다. prompt 문자열은 단 한 글자도 바뀌지 않았다.

만약을 위해 v0.134.0에서 재측정했으나, cap 분포도, cap-test의 두 번째 동작도, chain도 모두 이전과 동일했다. Issue #16479가 수정되지 않는 한, update를 통해서는 사라지지 않는다.

이미 Issue가 올라와 있었다

openai/codex#16479 ── 2026-04-01에 hannesrudolph 씨가 생성한 issue. 동일한 문제를 지적하고 있으며, proposed wording도 작성되어 있다:

- 1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
+ 1) After deciding to use a skill, open and read its `SKILL.md` in full. ...

cluedesc 씨가 patch까지 만들어 두었다 (cluedesc:fix/skills-read-skill-md-first). 다만 openai/codex는 invitation(초대)으로만 PR을 받고 있기 때문에 외부에서는 merge할 수 없다. Issue는 OPEN 상태이며, 4개의 댓글 모두 외부 작성자이고 OpenAI 팀으로부터의 응답은 제로다. 최종 업데이트는 2026-04-06으로, 2개월 가까이 움직임이 없다.

참고로 live main에는 동일한 wording이 2곳 (SKILLS_HOW_TO_USE_WITH_ABSOLUTE_PATHS + SKILLS_HOW_TO_USE_WITH_ALIASES)에 있다. cluedesc patch는 한쪽만 건드리고 있으며, 2026-04-24의 #19098에서 두 번째 const가 나중에 추가되었기 때문이다. current main에 rebase 및 양쪽 모두 업데이트가 필요하다.

나의 실측이 Issue의 주장을 뒷받침하는가

#16479는 wording(문구)을 변경해야 한다고 논의 측에서 지적하고 있다. runtime(런타임)에서 실제로 그런 일이 일어나고 있음을, 측정을 통해 세 가지 관점에서 보여준다.

~/.codex/sessions/

전체 209 세션의 cap(한계) 분포

71 세션이 sed를 사용하여 SKILL.md를 읽으려 시도했으며, 총 143개의 read(읽기)를 발생시켰다. 이를 model(모델)과 cap으로 나열하면 다음과 같다:

modelcap=220cap=240cap=260기타
gpt-5.580 (76%)10114 (cap-test 단계 읽기)
gpt-5.49227 (71%)0

동일한 prompt(프롬프트), 동일한 codex exec 경로에서 model만 바꾸면 분포가 역전된다. 이는 Issue(이슈)에서 말하는 "the model has to guess what counts as 'enough'" (모델이 무엇이 '충분한지' 추측해야 한다)라는 내용을 실측을 통해 그대로 보여준다.

Harness를 바꾸면 cap이 사라진다

통상적으로 Claude Code는 Claude에, Codex CLI는 OpenAI의 모델에 연결되어 있다. claudex를 통해 이 조합을 어긋나게 하면, Claude Code의 harness(하네스)를 유지한 채 gpt-5.5를 구동할 수 있다 ── 즉, 동일한 model을 Codex CLI의 prompt에 노출시키지 않는 경로다.

11 세션을 실행한 결과, first move(첫 번째 동작)가 Skill(...) 도구 호출인 경우는 11/11이었으나, sed -n '1,Np' .../SKILL.md인 경우는 0/11이었다. Codex CLI의 prompt가 없는 경로에서는 동일한 model이라도 cap은 애초에 발생하지 않는다.

Skill 자체에 "더 읽어라"라고 적으면, model은 읽는다

"cap-test"라는 skill(스킬)을 준비했다. Iron Law marker를 220행을 초과하는 위치에 두고, prefix(접두사) 내에서 "sed -n '221,$p'로 나머지를 읽어라"라고 명시했다. gpt-5.5에서 7/7, gpt-5.4에서 4/4가 marker를 획득했다 (= 두 번째 동작을 수행하여 221행 이후를 읽었다).

즉, model은 본래 partial(부분적) 읽기에 집착하는 것이 아니다. Codex CLI의 prompt가 "partial로 충분하다"라고 말하고 있기 때문에, 거기서 멈추고 있을 뿐이다.

사양(Specification) 측에서는 뭐라고 말하는가

Agent Skills 사양은 activation(활성화) 시에 "the entire file" (파일 전체)를 로드한다고 명시되어 있으며, SKILL.md 본체의 권장 상한은 500행 / 5000 tokens이다. 이는 Codex CLI의 prompt가 말하는 "partial로 충분하다"와 정면으로 모순된다.

지난 글에서 썼던 "대략 200행 안에 들어온다", "그러므로 220은 사양대로다"라는 설명은, 사양의 허용 범위(500행)를 절반 이하로 잘못 예측한 오독이었다.

Quaere 측에서 할 수 있는 말

지난 글에서 "SKILL.md 본체는 200행 이내로 유지하라"는 조언을 적었다. 이는 지금도 실용적인 측면에서는 유효하지만, 그 성격은 달라진다:

  • 사양(500행)에 맞추라는 조언이 아니라, Codex CLI의 prompt에서 기인한 현장의 cap에 맞추기 위한 workaround(임시 방편)이다. 구체적인 cap은 gpt-5.5에서 220, gpt-5.4에서 260이다.
  • 상위 단계의 wording이 수정되면 이 조언은 필요 없어진다.
  • Codex 이외의 harness (Claude Code, OpenCode, claudex 경로)에서는 처음부터 필요하지 않다.

Quaere의 skill 군을 200행 이내로 다시 작성하는 작업은 숙제로 남아 있다. 다시 작성한 후 재 eval(재평가)하면, 현재 README에 있는 eval 수치 (+37.7pp / +8.7pp)가 "Codex가 후반부를 읽지 않은 채 실행된 결과"인지, 아니면 "처음 200행만으로도 실질적으로 충분했던 것"인지를 비로소 분리하여 측정할 수 있게 된다.

측정 소스

raw data(원시 데이터)와 재현 절차는 gist에 올려두었다. cap-test skill과 Codex 세션 로그를 직접 grep 하여 확인할 수 있다.

이전 기사에서는 측정의 원시 데이터(raw data)만을 제시하고, "왜 220인가"에 대한 해석은 추측을 포함하여 결과적으로 몇 군데 틀린 부분이 있었다. 이번에 발견된 render.rs의 1행 + Issue #16479가 그 추측을 다시 써 내려가 준다.

Discussion

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0