핸드홀딩하려고 쌓아 둔 지시가 이제 발목을 잡는다 - Codex DX 담당자가 권하는 스킬과 프롬프트 정리

핸드홀딩하려고 쌓아 둔 지시가 이제 발목을 잡는다

TL;DR

• 전제는 관행이 바뀌는 속도인데 코딩 에이전트가 멀리 왔고 많은 핸드홀딩과 스캐폴딩을 요구했던 것이 더 이상 그렇지 않다는 것이다. 그래서 진단이 따라온다. 지난 1년간 에이전트를 써 왔다면 모델을 좋은 결과로 유도하려 애쓰며 비대한 지시를 많이 축적했을 텐데, 매 출시마다 그 가정을 재검토할 값어치가 있었지만 새 모델에서는 어느 때보다 중요하다
• 스킬을 많이 받는 기본 습관이 실수로 지목되는데 각 스킬의 이름과 설명이 모델 문맥에 실리고, 설명이 너무 길거나 스킬이 너무 많으면 Codex가 맞추려고 설명을 짧게 줄이기 시작한다. 결과가 나쁘다. 모델이 각 설명을 덜 보게 되어 무엇을 골라야 할지 알기 어려워지고, 설명들이 서로 모순되거나 나를 골라 달라는 기색이 과해 작업에 도움 안 되는 지시까지 싣게 된다.
• 처방은 세 가지인데 설명은 언제 써야 하는지 분명히 하면서 최대한 짧게 쓰고, 스킬을 읽는 것 자체가 문맥을 차지하니 루트 문서를 지원 문서를 가리키는 최소한의 라우터로 만들어 점진적 공개를 갖춘다는 것이다. 셋째가 반전이다. 모델이 뉘앙스와 모호함을 훨씬 잘 이해하게 됐으므로 조리법처럼 쓰인 과도하게 구체적인 지침은 이제 결과를 해친다
• AGENTS.md에서 지울 것도 명확한데 오타 수정에 매 편집 전 전체 저장소 지도를 요구하는 것은 과하고 그것은 문맥을 태우고 작업을 늦추는 훌륭한 방법이다. 테스트도 같아서 이전 모델은 테스트를 돌리도록 격려가 필요했지만 이제 스스로 하므로 같은 지시가 불필요한 테스트로 이어진다
• 경계와 지속성은 반대 방향의 조정을 요구하는데 먼저 묻게 만들려고 더한 강한 표현 때문에 판단이 훨씬 좋아진 새 모델이 실제로는 계속하기를 바랐을 지점에서 멈춰 버린다는 것이다. 그래서 처방이 나온다. 시작 전에 완료를 정의하고, 첫 구현 뒤 검토를 위해 멈추라는 요구가 모델을 더 이른 정지점으로 끌어당긴다는 점을 감안해 그것이 실제로 내려야 하는 결정인지 확인한다

Source

Rethinking skills and prompts for GPT-6 Astra — eric provencher(@pvncher, Codex DX @OpenAI), 2026년 9월 5일 · 조회 363.6만

[x.com/pvncher/status/2095991462416490862](https://x.com/pvncher/status/2095991462416490862)

Knowledge

축적된 지시가 부채가 되는 시점

코딩 에이전트는 멀리 왔고 모범 관행도 빠르게 바뀌고 있다. 많은 핸드홀딩과 스캐폴딩을 요구했던 것들이 더 이상 그렇지 않다. 지난 1년간 프로젝트에서 에이전트를 써 왔다면, 모델을 좋은 결과로 유도하려 애쓰면서 비대한 지시를 많이 축적했을 가능성이 크다. 매 출시마다 그 가정을 재검토할 값어치가 있었지만 새 모델에서는 어느 때보다 중요하다. 이 지시들은 여러 형태를 취하는데, 스킬과 AGENTS.md, 작업 프롬프트가 모두 모델이 일을 처리하는 방식을 형성한다.

스킬을 많이 받는 것이 실수인 이유

스킬 파일은 본질적으로 마크다운 파일로 저장된 프롬프트이고 때로 스크립트가 함께 묶여 있다. 특정 작업에만 필요한 워크플로 지침이나 플러그인 사용 지시에 가장 유용하다. 그런데 많은 사람이 프로젝트에 스킬을 많이 받는 것을 기본으로 삼는데, 그것이 실수다.

기제는 이렇다. 각 스킬은 이름과 설명을 갖고 모델이 언제 쓸지 알도록 그것이 모델 문맥에 실린다. 많은 설명이 너무 길고 스킬을 너무 많이 더하면 Codex가 맞추려고 설명을 짧게 줄이기 시작한다. 그러면 모델이 각 설명을 덜 보게 되어 어느 스킬을 골라야 할지 알기가 더 어려워진다.

더 나쁜 경우도 있다. 설명들이 서로 모순되거나 나를 골라 달라는 기색이 너무 과할 수 있다. 그 결과 모델이 실제로는 그 작업에 도움이 되지 않는 지시를 싣게 된다.

스킬을 쓰는 세 가지 원칙

Codex에게 스킬을 만들라고 요청한 적이 있다면 아마 스킬 생성기 스킬을 썼을 것이다. 실무에서 본 여러 실패 양상을 완화하려고 최근 그 지침을 몇 가지 방식으로 갱신했다.

첫째, 스킬 설명은 모델이 언제 그것을 써야 하는지 분명히 하면서 가능한 한 짧아야 한다. 나쁜 설명은 데이터베이스와 관련된 무엇이든 건드릴 때마다 그 스킬을 쓰게 밀어붙인다. 좋은 설명은 마이그레이션을 처리해야 할 때만 쓰게 한다.

둘째, 유용한 스킬의 핵심 표지 중 하나가 점진적 공개다. 스킬을 읽는 것 자체가 문맥을 차지해 압축에 더 가까워지게 만들고 그 작업에 적용되지 않을 수 있는 지침까지 들여온다. 워크플로가 여러 개인 스킬이라면 루트 문서를 지원 문서와 스크립트를 가리키는 최소한의 라우터로 만든다. 기준은 하나다. 지금 이 순간에 중요하지 않은 것을 읽도록 강요하지 않으면서 어디를 봐야 할지 알 만큼의 지침만 준다.

셋째, 많은 스킬이 정교한 일정표나 조리법처럼 쓰여 있다. 그런데 모델이 뉘앙스와 모호함을 이해하는 데 훨씬 나아졌다. 그래서 과도하게 구체적인 지침은 이전에 도움이 되던 곳에서 이제 결과를 해칠 수 있다.

저장소 스킬에는 부수 효과가 하나 더 있다. 그것은 다른 기여자의 에이전트도 안내하며 그들은 다른 모델을 쓸 수 있다. 어떤 모델에 도움이 되는 지침이 다른 모델을 과하게 제약할 수 있으니, 내가 남기는 지시를 어떤 모델들이 쓸지 고려해야 한다.

AGENTS.md에서 지워야 할 것들

AGENTS.md는 모델이 내 저장소에서 작업할 때마다 적용된다. 그러니 각 지시를 다시 보고 지금 하는 작업이 여전히 그것을 필요로 하는지 물어야 한다.

매 편집 전에 문서 더미나 전체 저장소 지도를 요구하는 것은 오타 수정에는 과하다. 모델은 모든 변경 전에 프로젝트 전체를 검토하도록 밀리지 않고도 무엇을 읽어야 할지 알아낼 수 있다. 매 편집 전에 파일을 읽게 프롬프트하는 것은 문맥을 태우고 작업을 늦추는 훌륭한 방법이다. 어떤 문서를 가리키는 것 자체는 맥락에 맞는 한 여전히 도움이 될 수 있는데, 그러려면 문서도 갱신된 상태로 유지해야 한다.

테스트도 마찬가지다. 이전 모델은 테스트를 돌리고 자기 작업을 확인하도록 격려가 필요했지만 이 모델은 스스로 하므로 같은 지시가 불필요한 테스트로 이어질 수 있다.

반대 방향의 조정도 필요하다. 이 모델은 철저하지만 작업을 어디까지 밀고 갈지에 대해서는 더 조심스러울 수 있다. 그래서 때로는 계속 가도록 약간의 밀어주기가 필요하고 안전하다고 아는 특정 워크플로에 대한 허가를 AGENTS.md로 줄 수 있다. 예컨대 로컬 테스트는 일회용 픽스처를 쓰고 프로덕션 접근이 없으니, 그것을 돌리고 요청된 변경으로 생긴 실패를 고치고 영향받은 테스트를 각 단계마다 승인을 묻지 않고 다시 돌리라고 적는다.

결정 경계와 지속성

경계를 어떻게 서술하는지에 세심히 주의를 기울여야 한다. 이전 모델이 허락 없이 대신 일을 해 버렸다면 먼저 묻게 만들려고 강한 표현을 더했을 수 있다. 그것이 유용할 때도 있다. 그런데 이 모델은 판단이 훨씬 좋으므로 그렇게 대해야 한다. 게다가 내 경계를 진지하게 받아들이므로, 실제로는 계속하기를 바랐을 지점에서 작업을 멈춰 버릴 수 있다.

지속성은 정반대로 뒤집혔다. 이전 모델이 요청을 받아 긴 구간을 계속하는 데 익숙했다면, 이 모델은 언제 멈출지에 대해 더 조심스럽게 느껄질 수 있다. 첫 구현에 도달하고 아직 할 일이 남았는데 내 검토를 받으러 돌아오기도 한다.

그래서 시작하기 전에 완료를 정의하는 것이 도움이 된다. 작업에 구현을 돌아가게 만드는 것과 결과를 점검하는 것, 실패한 것을 고치는 것이 포함된다면 그것을 요청의 일부로 만든다. 반대로 첫 구현 뒤 검토를 위해 멈추라는 요구는 모델을 더 이른 정지점으로 끌어당기므로, 그것이 실제로 내려야 하는 결정인지 확인해야 한다. 첫 시도를 넘어 계속 탐색하기를 원한다면 무엇을 탐색하고 어디서 멈춰야 하는지 말해 주면 된다.

새 모델은 집을 청소할 좋은 기회다. 이 글에서 논의된 것에 기반해 감사를 하라고 요청하고 그다음 이전에는 시도하지 않았을 것을 만들러 가면 된다.

더 생각해보기

• 스킬 설명을 짧게 하라는 원칙과 언제 쓸지 분명히 하라는 요구는 어디서 충돌하는가.
• 설명이 자동으로 잘려 나간다면 스킬 개수의 실질 상한은 어떻게 알 수 있는가.
• 나를 골라 달라는 기색이 과한 설명은 어떤 표현으로 판별할 수 있는가.
• 루트 문서를 라우터로 만드는 구조는 스킬이 하나의 워크플로만 가질 때도 유효한가.
• 조리법식 지침이 이제 해롭다는 판정은 신입 기여자의 학습에는 어떤 영향을 주는가.
• 저장소 스킬이 여러 모델에 적용된다면 모델별 분기를 문서에 써야 하는가.
• 매 편집 전 문서 읽기를 없애면 잘못된 가정으로 편집하는 위험은 어디서 막히는가.
• 테스트 지시를 지우는 판단은 어떤 프로젝트에서 위험해지는가.
• 강한 경계 표현을 완화하는 것과 안전을 유지하는 것은 어떻게 동시에 달성되는가.
• 완료를 미리 정의하라는 처방은 요구사항이 작업 중에 바뀌는 경우에 어떻게 적용되는가.