Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
AI 개발 과정에서 독자 유형에 따라 문체를 분리하는 방법을 제시합니다. AI 간의 상호작용은 영어 전보체(AXP/1) 같은 짧고 구조화된 형식으로, 사용자에게 보고하는 내용은 전문 용어 없는 일본어로 작성하여 토큰 사용량을 크게 줄였습니다. 이를 통해 개발 효율성과 가독성을 동시에 확보할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI에게 개발을 맡기다 보면, AI가 작성한 글의 독자가 두 종류라는 것을 깨닫게 됩니다. 하나는 저이고, 다른 하나는 또 다른 AI입니다. 저는 PC에 익숙하지 않다고 생각해서, 전문 용어가 가득한 보고서는 읽기 어렵습니다. 그런데 AI끼리의 상호작용까지 정중한 일본어 장문으로 하게 되면, 읽을 때마다 AI가 처리하는 문자량(토큰. AI의 사용량을 세는 단위)이 늘어나게 됩니다.
그래서 독자에 따라 문체를 분리했습니다. AI 간의 요청과 답변은 영어 전보체와 같은 짧은 형식으로 정하고, 저에게 하는 보고는 일본어만 사용하며 전문 용어를 쓰지 않도록 합니다. 동일한 리뷰 답변 한 건을 기준으로 측정했을 때, 토큰 수의 예상치는 418에서 167로 줄었습니다(o200k라는 토큰 계산 방식 기준). 이 글에서는 두 가지 문체 결정 방법, 짧게 해도 빠뜨리지 않는 것들, 저에게 하는 보고 규칙을 소개합니다. AI를 두 대 사용해 개발하는 사람과, AI에게 맡기는 쪽이 전문가가 아닌 사람들에게 적합한 이야기입니다.
저는 Claude Code(Anthropic의 터미널에서 작동하는 개발 지원 AI)와 Codex(OpenAI의 같은 종류의 AI) 두 가지를 사용하여 개인 개발을 하고 있습니다. 공통 규칙과 보조 스크립트는 agent-toolkit라는 리포지토리(파일과 그 변경 이력을 모아 놓는 곳)에 넣어두었습니다. 이 글의 메커니즘도 그 안에 포함되어 있습니다.
글의 독자와 작성 방식은 다음과 같이 분리했습니다.
| 상황 | 읽는 사람 | 작성 방식 |
|---|---|---|
| 한 AI에서 다른 AI로의 요청과 답변 (리뷰 요청 및 결과 포함) | AI만 | AXP/1 (직접 만든 형식. 영어 전보체 스타일) |
| AI에서 저에게 하는 보고 | 나 | 일본어만 사용. 전문 용어 없음 |
인계 문서・커밋 설명・설명란 (description) | 나와 다음에 작동할 AI | 일본어 그대로 유지 (전보체 대상 제외) |
AXP/1의 정의에는, 독자는 AI만이고 제가 원본 AXP를 읽을 필요가 없으며, 저에게 하는 보고는 담당 AI가 일본어로 해야 한다고 쓰여 있습니다. 예외로 지정한 것은 인계 문서・커밋 설명・제 눈에 띄는 모든 것・설명란입니다. 만약 제가 읽는 것까지 전보체 스타일로 만들면, 제가 이해할 수 없게 되기 때문입니다.
요청의 첫 줄에는 종류(작업・리뷰・질문), 이름, 추론 깊이(생각하는 양 설정)를 작성합니다. 그 아래에 다음 5가지를 나열합니다.
답변 쪽은 상태(ok・일부・실패・멈춤), 변경한 파일, 실행한 명령어와 결과(실측만), 미확인 사항, 주석의 5가지입니다. 다음은 형식을 보여주는 예시입니다 (값은 형식 설명을 위해 넣은 것이며, 실제 요청이 아닙니다).
@axp1 task id=<이름> eff=medium
goal: <무엇을 왜>
read: path:줄, path:줄
...
@axp1 re id=<이름>
st: ok
chg: path(+추가줄/-삭제줄)
...
리뷰 요청(종류는 rv)
은 읽기 전용이며, 쓰기나 실제 운영 환경에 대한 조작을 시키지 않습니다. 답변은 1지적당 1줄로 작성하며, 심각도가 높은 순서대로 나열합니다. 각 줄에는 위치, 구체적인 입력이나 상태, 그것으로 인해 발생하는 잘못된 결과, 최소한의 수정을 작성합니다. 지적이 없으면 none이라고 쓰고, 지적 개수를 부풀리지 않습니다. 마지막 줄에, 배포해도 되는지(ship・조건부・중단)와 그 근거로 읽었거나 실행한 것을 적습니다.
문체 규칙도 짧은 것입니다. 인사말, 서론, 요청 재진술, 사과를 쓰지 않고, 파일 내용은 붙이지 않고 경로와 줄 번호로 지정합니다. 기호는 -> (원인・다음 움직임), ~ (추정. 아직 측정하지 않음), ? (불확실), ! (필수), x (금지) 등으로 정했습니다. 전체를 영어의 ASCII 문자만으로 작성하고, 일본어를 남기는 것은 화면 문구 등을 인용할 때만 합니다.
문장을 짧게 하는 목적은 사용량을 줄이는 것입니다. 하지만, 짧아진 결과로 리뷰의 질이 떨어지면 의미가 없습니다. 그래서 AXP/1에는 압축해도 품질을 떨어뜨리지 않는 네 가지 항목을 정해 두었습니다.
~를 붙인 추정의 구분 - 미확인 사항(unv)이 네 가지가 적을 정도로 짧아진다면, 줄을 늘려도 괜찮습니다. 정의에서도 '정확성은 간결함보다 우선'이라고 쓰여 있습니다. 제가 제시한 방침 역시 'Claude와 Codex의 대화를 사람이 읽지 않아도 되니 품질을 유지하며 토큰 절약'이었습니다.
숫자 또한, 덜어내도 되는 부분과 덜어내지 않는 부분을 나누어 보고 있습니다. 과거 165건의 요청을 측정해 보니, 산문 부분은 평균 약 880이었습니다. 반면, 요청에 붙이는 코드의 차분(변경 부분)은 평균 약 6천이며, 이 부분은 압축하지 않고 그대로 전달합니다. 증거를 고정하기 위함입니다 (숫자의 단위는 기록에 적혀 있지 않으므로, 크기 비교에만 사용해 주세요). 줄일 수 있는 것은 AI가 작성하는 문장뿐입니다.
어떤 형식으로 반환할지는 AI의 기분에 따라 결정되지 않습니다. 요청의 첫 줄이 @axp1로 시작했는지 여부를 Codex를 호출하는 스크립트(Invoke-Codex.ps1)가 확인하여 결정합니다. @axp1가 문장 중간에 나오는 경우에는 인용으로 간주하여 무시합니다.
Codex 측에서는 설정 파일(~/.codex/AGENTS.md)의 끝 부분에 AXP/1 전체를 배치했습니다. 동기화용 스크립트가 연결되어 있습니다. Claude Code 측은 공통 규칙 요청 작성 절에서 참조합니다. 요청 양식, Codex 호출 스크립트, 리뷰용 스크립트, 서브 에이전트(Claude Code가 호출하는 보조 AI)까지 네 가지 모두 같은 형식으로 통일했습니다.
이 점검 과정은 테스트 역할도 했습니다. 자체 점검 스크립트에 AXP 항목을 추가하고, 고장 난 버전으로 작동하는지 확인했습니다. Codex에게 리뷰를 요청하여 중간 정도 2건과 경미한 1건의 지적을 채택했고, 재확인에서 지적이 사라졌습니다.
공통 규칙에는 제가 볼 수 있는 문장은 일본어만이라고 적혀 있습니다. 중간에 한마디도 예외가 아닙니다. 영어를 사용할 수 있는 경우는 코드와 인용뿐이며, 이 역시 ```로 감쌉니다. 보고에서는 전문 용어를 사용하지 않고, 무엇을 했는지, 무엇이 남아있는지를 증거를 붙여 짧게 전달하는 규칙입니다.
세부적인 규정들 또한 제가 혼란스럽지 않기 위한 것입니다.
마지막 규정은 전보체 unv란과 같은 생각입니다. 문체를 두 개로 나누더라도, '확인한 것과 확인하지 않은 것을 섞지 않는다'는 골격은 공통적입니다.
하지만 규칙만 작성해서는 영어가 새어 나왔습니다. 도입 전 기록에서 답변 문 1,763건 중 683건이 영어였습니다. 규칙을 지키게 하는 장치가 필요하다고 느껴져서, 영어 문장을 발견하면 되돌리는 후크(Claude Code가 동작 전후에 자동으로 실행되는 작은 스크립트)를 추가했습니다. 다만, 중간의 한마디는 표시 전에 막을 방법이 없어, 일단 화면에 나옵니다. 도입 전 측정 결과에서 중간의 한마디의 18%가 영어였습니다. Claude Code 본체의 화면 문구(허가를 요청하는 Yes/No 등)는 애초에 고칠 수 없습니다.
| 담당 | 수행 내용 |
|---|---|
| 저 | 방침 결정( |
자신의 환경에서 시도해 볼 수 있는 것은 다음 세 가지입니다.
가장 첫걸음으로는, 요청에 '목적・자료 파일・건드리지 않을 범위・완료 조건' 네 가지를 작성하고, 답변에는 반드시 '미확인' 항목을 만드는 것만으로도 변화가 있습니다. 그 위에 더해, 같은 요청을 3번 작성했다면 스크립트 등의 도구로 만든다는 규칙도 제가 세우고 있습니다.
