TL;DR

• Claude Code(데스크톱 버전)와 Codex CLI(ChatGPT Pro 플랜)를 병용하는 개발 환경을 구축하고, 막혔던 5가지 지점을 메커니즘 측면에서 정리했다.
• CLAUDE.md는 글로벌(~/.claude/)과 프로젝트 직하의 2층 구조로 되어 있으며, 글로벌은 모든 세션에서 매번 읽히기 때문에 사업 전략과 같은 긴 문장은 @ 임포트(~ 확장 대응·중첩 최대 4홉)를 통해 외부로 빼는 것이 정답이다. 슬래시 명령어(Slash command)·스킬(Skill)·MCP 도구는 서로 다른 확장 메커니즘이며, 스킬은 자연어 요청으로부터 자동 선택되므로 명령어 이름을 암기할 필요는 없다.
• "기존 내용과 병합해줘"라는 지시는 의미적 모순 검출을 보장하지 않으므로, "모순이 없는지 확인한 후 추가해줘"라고 지시에 명시하는 것이 안전하다.
• MCP 연결은 세션 시작 시 캐시되므로 설정을 변경하려면 재연결이 필요하며, 임베디드 브라우저(Browser pane)는 평소 사용하는 Chrome과 상태를 공유하지 않는 등 공식 문서에 적혀 있지 않은 실무적인 사양이 몇 가지 있었다.

마찬가지로 Claude Code와 Codex를 병용하는 환경을 구축하려는 분들에게 참고가 되길 바라며, 판단의 기록으로서 남깁니다.

Claude Code(데스크톱 버전)와 Codex CLI를 병용하는 환경을 구축했을 때, 막혔던 부분은 설치 절차가 아니라 모두 "도구 간의 경계"였다. CLAUDE.md의 읽기 설계, 슬래시 명령어와 스킬의 차이, MCP 연결의 라이프사이클, 임베디드 브라우저의 상태 분리——5가지 막혔던 지점을 메커니즘 측면에서 정리한다.

대상: Claude Code(CLI/데스크톱)를 사용하기 시작한 사람, Codex CLI와의 병용 환경을 구축하고 싶은 사람, CLAUDE.md의 위치 선정에 고민 중인 사람.

검증 환경: Claude Code 데스크톱 버전(macOS) / Codex CLI(ChatGPT Pro 플랜) / chrome-devtools MCP

이 기사의 구성

나는 환경 구축 과정에서 5번 막혔다. 개별 현상은 "흔히 있는 일"이지만, 원인은 모두 도구의 담당 범위를 실제보다 넓게 예측한 것으로 귀결된다. 본 기사에서는 현상이 아닌 메커니즘을 축으로 다음 5가지를 해설한다.

• CLAUDE.md의 2층 구조와 @ 임포트 사양
• 슬래시 명령어/스킬/MCP 도구의 구별
• 기존 설정 파일에 추가하는 것이 모순을 낳는 구조와 대책
• 실행 환경(터미널/코드 탭)에 따른 명령어 가용성
• MCP 연결의 라이프사이클과 Browser pane의 상태 분리

@ 임포트 사양

1. CLAUDE.md의 2층 구조와

무엇이 일어났는가

사업 전략도 도구 사용법도 모두 글로벌 CLAUDE.md(~/.claude/CLAUDE.md)에 쓰려고 했다.

메커니즘

CLAUDE.md에는 읽기 범위(Scope)가 다른 2층이 있다.

글로벌에 둔 내용은 매 세션 반드시 컨텍스트(Context)에 포함된다. 즉, 사업 전략과 같은 긴 문장을 글로벌에 두면, 무관한 코딩 세션에서도 매번 그만큼의 컨텍스트를 소비한다. 반대로 여러 프로젝트에서 참조하고 싶은 내용을 프로젝트 측에 가두면, 이번에는 참조할 수 없는 프로젝트가 생긴다.

이를 해결하는 것이 @ 임포트다. CLAUDE.md 내에 @path/to/file이라고 쓰면, 세션 시작 시 해당 파일의 내용이 인라인으로 전개된다. 공식 문서에서 확인할 수 있는 사양은 다음과 같다.

• @~/dev/xxx/file.md와 같이 홈 디렉토리를 포함하는 경로를 지원한다 (쉘 확장(Shell expansion)이 아니라, Claude Code 자체의 임포트 파서가 해결한다).
• 상대 경로는 임포트 원본 파일로부터의 상대 경로로 해결된다 (워킹 디렉토리 기준이 아니다).
• 읽기 타이밍은 세션 시작 시이다. 시작 후에 임포트 대상을 수정해도 현재 세션에는 반영되지 않는다.
• 중첩(Nest)은 **최대 4홉(Hop)**이다 (참조 대상이 다시 @ 참조를 가질 수 있는 횟수의 상한).

설계 지침

이 사양으로부터 배치 장소의 원칙을 도출할 수 있다.

• Global = 도구 사용법 (이미지 생성 규칙, Git 운용, 브라우저 확인의 구분 사용 등, 어떤 프로젝트에서도 동일한 것)
• 공유하고 싶은 긴 문장 = 중립적인 1개 파일 (예: ~/dev/content-ops/00_docs/strategy-ladder.md)
• 각 프로젝트의 CLAUDE.md = (@ 참조의 1행 @~/dev/content-ops/00_docs/strategy-ladder.md)

이렇게 하면 "필요한 곳에서만 읽히는" 상태가 됩니다.

2. 슬래시 커맨드(Slash Command) / 스킬(Skill) / MCP 도구의 구분

무엇이 일어났는가

"이미지 생성은 /codex로 입력하면 되는가?"라고 생각했습니다. 실제로는 /codex:review는 코드 리뷰용 커맨드였고, 이미지 생성은 "codex-imagegen"이라는 별도의 스킬이었습니다.

메커니즘

Claude Code의 확장 메커니즘은 최소 3가지 종류가 있으며, 각각 호출 방식이 다릅니다.

중요한 점은, 스킬은 자연어로부터 자동 선택된다는 점입니다. CLAUDE.md에 "이미지는 codex-imagegen 스킬로 생성한다"라는 규칙을 적어두면, "썸네일을 16:9로 3안 생성해줘"라는 요청만으로 올바른 스킬이 선택됩니다. 커맨드 이름을 암기할 필요는 이 구조 위에서는 불필요합니다.

3. 기존 설정 파일에 추가하는 것이 모순을 낳는 구조와 대책

무엇이 일어났는가

이미지 양산용 자작 파이프라인(OpenAI Images API 직접 호출)이 작동 중인 리포지토리의 CLAUDE.md에, "이미지 생성은 codex-imagegen 스킬로 수행한다. API 키 사용 및 스크립트 자작은 금지한다"라는 규칙을 "기존 내용과 병합하여" 추가하도록 시도했습니다. 이 두 가지는 정면으로 모순됩니다 (금지 규칙이 기존의 주력 파이프라인을 무효화함).

Claude Code 측에서 추가하기 전에 기존 파일을 읽고 모순을 감지하여 정지했기 때문에 사고로 이어지지는 않았습니다. 최종적으로는 용도별 라우팅(상품 본체 = 투명 PNG 필수이므로 API 유지 / 주변 이미지 = codex-imagegen)으로 정리하였고, 판단 경위를 ADR에 기록했습니다.

메커니즘과 대책

"병합해줘"라는 지시는 중복의 통합을 지시할 뿐, 의미적인 모순의 감지를 보장하지 않습니다. 추가 내용과 기존 내용이 양립할 수 있는지에 대한 판단은 명시적으로 지시하지 않는 한 최선(Best Effort)을 다할 뿐입니다.

대책은 지시의 템플릿화입니다.

추가하기 전에, 기존 내용과 모순되지 않는지 확인한 후 추가해줘.
모순되는 경우에는 실행하지 말고, 먼저 알려줘.

또 다른 배움은, 기술적 제약이 설계 판단을 규정하고 있었다는 점입니다. 이번 케이스에서는 "gpt-image-2(codex-imagegen 경유)는 투명 배경을 지원하지 않는다"라는 제약이 있었고, 투명 PNG가 상품 사양인 이상, 일원화라는 선택지는 애초에 존재하지 않았습니다. 기존 파이프라인이 API를 직접 호출했던 것은 합리적인 설계였다는 사실을 모순 감지 덕분에 재확인할 수 있었습니다. 이러한 "왜 2개의 계통으로 만들었는가"는 구두로 전달하면 사라지기 쉬우므로, ADR(Architecture Decision Record)로 남기는 것을 권장합니다.

/plugin은 코드 탭에서 사용할 수 없음

4. 실행 환경에 따른 커맨드의 가용성 — ### 무엇이 일어났는가

데스크톱 앱의 코드 탭에서 /plugin을 실행하려고 했으나, 사용할 수 없었습니다.

메커니즘

/plugin이나 /permissions, /config 등의 일부 커맨드는 터미널 상에서 대화형 패널을 여는 UI로 구현되어 있습니다. 데스크톱 앱의 코드 탭은 실행 환경이 다르기 때문에, 이러한 대화형 패널을 표시할 수 없습니다.

"커맨드가 존재한다"는 것과 "현재 실행 환경에서 사용할 수 있다"는 것은 별개입니다. 사용할 수 없는 경우에는 터미널에서 claude를 실행하여 수행하면 작동합니다. 반대로, 일상적인 표시 확인 등은 코드 탭 내장된 Browser pane을 사용하는 것이 완결성이 높으며, 환경마다 특화된 분야가 있습니다.

5. MCP 연결의 라이프사이클과 Browser pane의 상태 분리

마지막 걸림돌은 하나의 요청으로부터 세 가지 사양(specification)에 연속으로 부딪힌 사례였습니다. 발단은 "지금 Chrome에서 열려 있는 페이지의 스크린샷을 찍어줘"라는 요청이었습니다.

5-1. MCP 서버 설정은 세션 시작 시 캐시된다

chrome-devtools MCP 서버의 실행 인자(argument)를 변경한 직후에 사용하려 했으나, 변경 사항이 반영되지 않았습니다. **MCP 연결은 세션 시작 시 확립 및 캐시(cache)**되기 때문에, 설정 변경을 반영하려면 새로운 세션을 열거나 /mcp reconnect <서버명>을 실행해야 합니다.

5-2. Browser pane은 일반 Chrome과 상태를 공유하지 않는다

"지금 열려 있는 페이지"라는 지시는 성립하지 않았습니다. 코드 탭 내장 Browser pane은 **독립된 임베디드 브라우저(embedded browser)**이며, 사용자가 평소 사용하는 Chrome의 탭, 세션, 로그인 상태를 전혀 공유하지 않습니다. 대상 URL은 명시적으로 전달해야 합니다.

참고로, 평소 사용하는 Chrome을 직접 조작하고 싶다면 chrome-devtools MCP(또는 브라우저 확장형 연동)라는 별도의 경로를 이용해야 합니다. "AI에게 보여주고 싶은 화면이 어느 브라우저에 있는가"를 의식하며 구분해서 사용하게 됩니다.

5-3. 도구의 타임아웃 보고는 실패를 의미하지 않는다

Browser pane의 실행이 "타임아웃되었습니다"라고 보고되었으나, 탭의 상태를 확인해보니 페이지 전환 자체는 성공해 있었습니다(탭의 origin이 전환된 도메인으로 바뀌어 있었습니다). 도구의 응답 대기가 타임아웃되었을 뿐, 조작 자체는 백그라운드에서 완료된 케이스입니다.

타임아웃 보고를 받으면, 재시도(retry)를 하기 전에 현재 상태를 확인하는 것(탭 목록 보기, 스크린샷 시도)이 더 빠를 때가 있습니다. "실패했다"라는 보고와 "실패했다"라는 사실은 별개의 것입니다.

요약 — 걸림돌은 모두 "경계"였다

AI 에이전트는 "부탁하면 무엇이든 해줄 것"처럼 보이지만, 실제로는 도구마다 담당 범위가 나누어져 있습니다. 환경 구축의 본질은 설치 절차가 아니라, 이 경계선을 자신의 멘탈 모델(mental model)에 올바르게 다시 그리는 작업입니다.

이 5가지 걸림돌의 "실황 중계" 버전(실제 대화 흐름)과 그대로 사용할 수 있는 CLAUDE.md 전문, 사고 치지 않는 지시 템플릿, 실행 큐(execution queue) 만드는 법은 note에 정리해 두었습니다(유료) → 【note URL·공개 후 교체】

AI 코딩 시대의 설계 판단을 매달 검증하는 멤버십 "부서지지 않는 설계 연구소"도 운영 중입니다 → https://note.com/hitori_dougu/membership

Discussion