673 ／ 673

클로드 코드에서 코덱스로, 익숙한 작업법 그대로 옮기기

6 분 소요

클로드 코드를 오래 쓴 사람에게 코덱스는 새 도구이면서도 낯익다. 터미널에서 저장소를 열고, 프로젝트 지침을 읽히고, 계획을 세운 뒤 파일을 고치고 테스트한다. 이름과 명령은 달라도 작업의 뼈대는 같다.

차이는 이사 비용이다. 예전에는 CLAUDE.md와 스킬, MCP 설정을 하나씩 다시 만들었다. 지금은 코덱스가 클로드 코드의 설정과 최근 작업을 가져온다. 첫날에는 새 문법 암기 대신, 이미 잘 닦아 둔 작업 방식을 옮기고 차이만 확인하면 된다.

첫 10분은 가져오기에 쓴다

ChatGPT 데스크톱 앱에서는 Settings → Import를 열어 Claude Code를 선택한다. 코덱스 CLI에서는 세션을 시작한 뒤 /import를 입력한다. CLI는 최근 30일 대화 가운데 최대 50개를 가져올 수 있다.

OpenAI 공식 문서가 밝힌 이전 범위는 꽤 넓다.

클로드 코드에서 쓰던 것	코덱스에 자리 잡는 곳
지침 파일	`AGENTS.md`
`settings.json`	`config.toml`
스킬	Skills
플러그인	Plugins
프로젝트 폴더	같은 폴더를 쓰는 Projects
프로젝트 메모리	Memories
최근 대화	ChatGPT·Codex chats
MCP 설정	Codex MCP 설정
Hooks	Codex Hooks
Slash commands	Skills
Subagents	Codex Subagents

가져오기는 기존 클로드 코드 설정을 바꾸거나 지우지 않는다. 다만 MCP 인증, 환경 변수, 도구 권한, 경로를 다시 확인해야 한다. 가져왔다는 사실과 작동한다는 사실은 다르다. 첫 테스트는 작은 읽기 작업, 작은 파일 수정, 빌드 실행 순서가 안전하다.

CLAUDE.md의 자리는 AGENTS.md가 맡는다

클로드 코드에서 CLAUDE.md가 프로젝트의 작업 규칙이었다면 코덱스에서는 AGENTS.md가 같은 자리를 맡는다. 저장소 구조, 빌드 명령, 문체, 금지사항, 완료 기준을 적어 두면 에이전트가 작업 전에 읽는다.

범위	권장 위치	넣을 내용
개인 공통	`~/.codex/AGENTS.md`	답변 언어, 보고 방식, 개인 작업 습관
저장소 전체	`repo-root/AGENTS.md`	구조, 실행 명령, 검증 기준, 변경 원칙
특정 폴더	`하위폴더/AGENTS.md`	그 영역에만 적용되는 세부 규칙

작업 위치에 가까운 AGENTS.md가 더 구체적인 지침으로 작동한다. 전역 파일에 프로젝트 규칙까지 쌓지 않고, 저장소 규칙은 저장소에 남기는 편이 관리하기 쉽다.

이 블로그 저장소라면 다음 정도가 출발점이다.

# 블로그 작업 규칙

- 포스트는 `_posts/YYYY-MM-DD-slug.md`에 작성한다.
- front matter에 title, date, categories, tags, permalink를 넣는다.
- 본문은 단정체로 쓰고 콜론 헤딩과 이모지를 쓰지 않는다.
- 최신 제품 정보는 공식 문서에서 확인한다.
- 기존 사용자 변경과 무관한 파일은 건드리지 않는다.
- 완료 전에 링크 검사, Jekyll 빌드, diff 검토를 실행한다.
- 검사하지 못한 항목은 성공했다고 쓰지 않는다.

좋은 지침은 길이보다 판별력이 만든다. 코덱스가 같은 실수를 두 번 반복했을 때 한 줄을 추가하면 된다. 아직 일어나지 않은 문제까지 상상해 거대한 규칙집을 만드는 순간, 중요한 규칙이 묻힌다.

스킬은 있다, 반복 프롬프트보다 오래 남는다

코덱스에도 스킬이 있다. 스킬은 특정 업무의 절차, 참고자료, 선택적 스크립트를 한 폴더에 묶은 작업법이다. 기본 파일은 SKILL.md다.

.agents/skills/
└── blog-post-review/
    ├── SKILL.md
    ├── references/
    │   └── style-guide.md
    └── scripts/
        └── check_post.py

코덱스는 모든 스킬의 전문을 처음부터 읽지 않는다. 먼저 이름과 설명을 보고, 현재 요청과 맞는 스킬의 SKILL.md를 선택해 읽는다. 긴 프롬프트를 늘 붙여 넣지 않아도 되는 이유다.

개인 공통 스킬은 $HOME/.agents/skills, 저장소 전용 스킬은 .agents/skills에 둔다. $skill-creator를 호출하면 첫 초안을 만들 수 있다. 사용자가 $스킬이름으로 직접 부르거나, 요청이 설명과 일치할 때 코덱스가 고른다.

교육자라면 다음 다섯 가지부터 자산으로 만들 만하다.

스킬	입력	결과물
수업 설계 검토	성취기준, 수업안	질문·탐구·피드백을 보강한 지도안
교원 연수 자료	대상, 시간, 주제	PPT, 실습지, 강사 노트
교육 데이터 분석	XLSX, 연구 질문	검정 결과, 차트, 해석 보고서
블로그 글 작성	주제, 자료, 독자	Jekyll 포스트와 검증 기록
웹 도구 점검	저장소, 요구사항	수정 코드, 테스트, 화면 확인

반복 프롬프트를 세 번째 복사하는 순간이 스킬을 만들 시점이다. 스킬은 품질 기준까지 재현하는 작은 작업 시스템이다.

MCP와 플러그인은 외부 세계를 연결한다

AGENTS.md와 스킬은 코덱스가 어떻게 일할지를 정한다. MCP는 코덱스가 어디까지 손을 뻗을지를 정한다. GitHub, Google Drive, Figma처럼 저장소 밖에 있는 자료와 도구가 필요할 때 MCP가 연결 통로가 된다.

플러그인은 스킬과 MCP, Hooks 같은 기능을 설치 가능한 묶음으로 만든다. 이미 검증된 작업 묶음이 있다면 플러그인을 설치하고, 내 방식이 고유하다면 스킬부터 만든 뒤 필요할 때 플러그인으로 묶는 순서가 가볍다.

필요	선택
이번 작업에만 필요한 지시	현재 프롬프트
저장소에서 늘 지킬 규칙	`AGENTS.md`
여러 번 반복할 절차	Skill
GitHub·Drive 같은 외부 시스템	MCP 또는 App connector
설치하고 공유할 기능 묶음	Plugin
정해진 시각에 반복할 일	Automation
실행 전후 강제 검사	Hook

도구를 많이 연결한다고 하네스가 좋아지지는 않는다. 매주 손으로 반복하는 이동 하나를 없애는 연결이, 쓰지 않는 MCP 열 개보다 낫다.

프롬프트는 네 칸이면 충분하다

OpenAI의 코덱스 모범 사례는 좋은 요청을 목표, 맥락, 제약, 완료 조건으로 정리한다. 클로드 코드에서 잘 작동하던 명시적 지시는 그대로 유효하다.

목표
클로드 코드 사용자를 위한 코덱스 입문 글을 새 포스트로 작성해.

맥락
저장소의 관련 비논문 글 5편과 CLAUDE.md의 문체 규칙을 참고해.

제약
OpenAI 제품 정보는 공식 문서만 사용해.
단정체로 쓰고 콜론 헤딩, 이모지, 상투적인 AI 표현을 빼.
기존 파일의 사용자 변경은 보존해.

완료 조건
글 파일 생성, 내부·외부 링크 검사, 로컬 Jekyll 빌드,
diff 검토, 안티슬롭 검사까지 끝내고 증거를 요약해.

네 칸의 마지막이 가장 중요하다. 완료 조건이 없으면 에이전트는 파일을 저장한 순간 일을 끝냈다고 판단하기 쉽다. 빌드 성공, 테스트 통과, 화면 확인, 링크 응답처럼 관찰 가능한 기준을 적어야 한다.

플랜 모드는 잘못된 구현을 일찍 버린다

범위가 작고 답이 분명하면 바로 실행해도 된다. 여러 파일을 건드리거나 요구가 모호하면 Plan 모드에서 먼저 경계를 정한다. /plan을 열거나 작업 전 인터뷰를 요청하면 된다.

아직 구현하지 마. 먼저 나를 인터뷰해.
사용자, 핵심 문제, 최소 기능, 개인정보 위험,
검증 방법이 결정될 때까지 질문한 뒤 계획을 작성해.

계획은 에이전트가 시간을 더 쓰게 만드는 문서가 아니다. 잘못된 구현을 일찍 버리는 장치다. 특히 학교 자료, 학생 데이터, 외부 API가 얽힌 작업은 구현 전에 데이터의 흐름과 공개 범위를 먼저 그려야 한다.

코덱스에서 먼저 익힐 명령은 여덟 개다

명령	쓸 때
`/import`	Claude Code 설정과 최근 작업을 옮길 때
`/plan`	복잡하거나 애매한 작업을 설계할 때
`/review`	커밋·브랜치·미커밋 변경을 검토할 때
`/skills`	사용할 수 있는 스킬을 찾을 때
`/plugins`	플러그인을 찾고 관리할 때
`/status`	현재 모델·권한·세션 상태를 볼 때
`/compact`	긴 대화를 핵심 결정 중심으로 줄일 때
`/fork`	같은 맥락에서 다른 해법을 시험할 때

명령 이름을 전부 외울 필요는 없다. 첫 주에는 가져오기, 계획, 검토, 상태 확인만 손에 익혀도 작업 흐름이 잡힌다.

교육자의 일은 답변보다 파일에 가깝다

일반 챗봇 사용자는 좋은 답을 기대한다. 교육자의 실제 업무는 답으로 끝나지 않는다. 수업안은 DOCX가 되고, 설문 분석은 XLSX와 차트가 되며, 연수안은 PPT와 강사 노트가 된다. 블로그 글은 저장소 안의 Markdown 파일이어야 한다.

그래서 코덱스에는 산출물과 검증을 함께 요청해야 한다.

약한 요청	작업이 끝나는 요청
수업안 만들어 줘	지도안과 활동지를 파일로 만들고 학년 수준과 시간 합계를 검사해
설문 분석해 줘	원본을 보존하고 분석 XLSX와 해석 보고서를 만든 뒤 계산을 재검산해
블로그 글 써 줘	포스트 파일을 만들고 링크, 빌드, diff, 문체를 검사해
웹 앱 만들어 줘	구현한 뒤 테스트하고 PC·모바일 화면과 오류 상태를 확인해

코덱스의 가치는 코드를 대신 타이핑하는 데만 있지 않다. 자료를 읽고, 판단을 구조화하고, 실제 파일을 만들고, 결과를 다시 확인하는 한 묶음의 일을 맡길 때 차이가 커진다.

권한은 작업의 경계선이다

에이전트가 파일과 셸, 인터넷을 다루면 권한 설정은 작업 품질의 일부가 된다. 승인 모드는 언제 사용자에게 물을지를 정하고, sandbox는 어디까지 읽고 쓸지를 정한다. 처음에는 기본 권한을 유지하고 신뢰하는 저장소의 필요한 작업에서만 범위를 넓히는 편이 안전하다.

학교 현장에서는 이 원칙이 더 단단해야 한다.

학생 이름, 연락처, 사진, 상담 기록은 작업 폴더에 넣지 않는다.
분석이 필요하면 식별자를 바꾸고 최소 열만 남긴 사본을 만든다.
API 키와 토큰은 코드나 Markdown에 적지 않는다.
메시지 전송, 게시, 삭제, 배포는 대상과 내용을 마지막에 다시 본다.
테스트 실패를 없애려고 테스트 기준을 낮추지 않았는지 diff에서 확인한다.

빠른 실행보다 되돌릴 수 있는 실행이 오래 간다.

클로드 코드 사용자의 7일 전환 순서

날짜	해볼 일	남는 자산
1일차	`/import` 실행 후 작은 읽기·수정·빌드 시험	이전 상태 점검표
2일차	`CLAUDE.md`를 바탕으로 짧은 `AGENTS.md` 정리	저장소 규칙
3일차	기존 이슈 하나를 수정하고 `/review` 실행	검증된 커밋
4일차	세 번 이상 반복한 프롬프트를 스킬로 변환	첫 `SKILL.md`
5일차	수업안·PPT·XLSX 중 하나를 실제 파일로 완성	교육 자료 1종
6일차	작은 웹 도구를 계획하고 브라우저까지 점검	작동하는 MVP
7일차	반복 실수를 찾아 `AGENTS.md`와 스킬 수정	개인 하네스 v1

첫 주에는 모든 기능의 숙달보다 내 일이 잘 끝나는 한 경로를 만드는 데 집중한다. 한 경로가 안정되면 두 번째 스킬과 첫 자동화는 자연스럽게 따라온다.

도구를 바꿔도 남는 것은 작업 구조다

이 블로그에서 클로드 코드를 다루며 반복해서 확인한 원칙이 있다. 신선한 컨텍스트가 비대한 컨텍스트보다 낫고, 화려한 도구보다 실제 문제를 해결하는 도구가 낫다. 완료 조건 없는 자동화는 중간에서 멈추며, 짧은 지침 파일 하나가 과잉 구현에 브레이크를 건다. 스킬은 내 작업 방식을 작은 단위로 축적할 때 가치가 생긴다.

이 원칙은 코덱스에서도 바뀌지 않는다. CLAUDE.md는 AGENTS.md가 되고 명령 몇 개가 달라질 뿐이다. 도구의 이름보다 목표, 맥락, 경계, 검증을 설계하는 힘이 오래 남는다.

클로드 코드에서 쌓은 시간은 초기화되지 않는다. 이미 가진 작업 감각을 새 하네스에 맞게 번역하는 과정이 곧 코덱스 입문이다.

김진관(닷커넥터)

Categories

Tag Cloud

최근 방문

저서