도구에 종속되지 않는 AI 작업 환경 구성

AI 도구를 쓰다 보면 금방 도구별 설정이 늘어납니다.

Claude Code에는 Claude Code용 지침이 있고, Codex에는 Codex용 지침이 있습니다. 처음에는 자연스럽습니다. 하지만 어느 순간부터 같은 규칙을 두 번 고치고, 한쪽에서 배운 실패를 다른 쪽에서는 다시 반복합니다.

제가 만들고 싶었던 것은 특정 도구에 갇힌 설정이 아니었습니다.

모델과 클라이언트는 바뀔 수 있지만 제가 일하는 방식은 계속 남아야 했습니다. 그래서 여러 AI 도구가 같은 기준 원본을 바라보는 구조를 만들었습니다.

핵심은 단순합니다.
공통 자산은 공통 작업 공간에 두고, 각 도구의 설정 경로는 그 자산을 심볼릭 링크나 생성 결과로 바라봅니다.

공통 작업 공간
  -> 도구별 설정 경로
  -> 도구별 설정 경로

이 구조에서 중요한 것은 파일 위치보다 책임 분리입니다. 항상 읽혀야 하는 원칙, 반복 절차, 실행을 막아야 하는 가드레일, 다음 실행에 영향을 주는 메모리, 독립 작업자 역할을 서로 다른 계층으로 나눴습니다.

왜 도구 중립 구조가 필요했나

AI 도구는 빠르게 바뀝니다. 오늘은 Codex가 편하고, 내일은 Claude Code가 더 적합할 수 있습니다. 특정 도구의 설정 파일에 지식을 직접 쌓으면 도구를 바꿀 때마다 운영 방식이 같이 흔들립니다.

문제는 단순한 중복이 아닙니다. 규칙이 여러 곳에 복사되면 어느 쪽이 최신인지 모호해집니다. 예를 들어 secret 파일을 읽지 말라는 규칙이 한 도구에만 있으면, 다른 도구에서는 같은 실수를 할 수 있습니다. PR 형식, git push 제한, 디버깅 절차, 메모리 저장 위치도 마찬가지입니다.

그래서 기준을 이렇게 잡았습니다.

기준	의미
원본은 하나	공통 지침과 자산은 `공통 작업 공간`을 기준 원본으로 둡니다
도구별 경로는 산출물	각 도구의 설정 경로는 원본이 아니라 링크 또는 생성 결과입니다
절차는 늦게 읽기	항상 필요한 원칙만 전역 지침에 두고, 작업별 절차는 스킬로 불러옵니다
위험은 실행 전에 차단	명령을 실행한 뒤 후회하지 않도록 훅과 규칙에서 막습니다
기억은 목적별로 분리	반복 실패, 장기 지식, 운영 절차를 한 파일에 섞지 않습니다

전체 계층

제 환경은 크게 다섯 계층으로 나눕니다.

사용자 요청
  -> AGENTS.md
  -> 훅 / 규칙
  -> 스킬 / 에이전트
  -> 메모리 / 지식 / 실행 절차
  -> 도구별 설정 경로

AGENTS.md는 커널에 가깝습니다. 모든 도구가 읽는 기본 원칙만 둡니다. 반대로 특정 작업에서만 필요한 절차는 스킬에 둡니다. Django 작업이면 Django guide를, PR 생성이면 PR creator를, 보안 검토면 security guide를 읽는 식입니다.

이렇게 하면 항상 로드되는 문맥이 줄어듭니다. 동시에 중요한 운영 규칙은 도구가 달라져도 유지됩니다.

훅: 실행 전에 막는 계층

훅은 에이전트가 도구를 실행하기 전에 보는 안전장치입니다. 프롬프트로 "조심해"라고 말하는 것보다 위험한 명령을 실제로 막는 편이 낫습니다.

제 환경의 훅은 주로 도구 실행 직전 단계에서 동작합니다. 예를 들어 다음 같은 일을 합니다.

가드레일	막는 것	이유
git 명령 가드레일	`git reset --hard`, 위험한 checkout, main 병합 자동 실행	사용자 변경 유실과 의도하지 않은 배포 방지
민감 파일 가드레일	`.env`, SSH key, AWS credential 같은 민감 파일 접근	비밀값이 프롬프트나 로그로 들어오는 것을 방지
운영 환경 가드레일	운영 비밀값이나 인프라 쓰기 성격의 명령	에이전트가 운영 상태를 직접 바꾸지 않도록 제한

이번 블로그 repo에서도 비슷한 방향을 적용했습니다. main은 삭제와 히스토리 재작성을 막고, 일반 fast-forward push만 허용합니다. 작은 글 수정은 빠르게 반영하되, 되돌리기 어려운 작업은 막는 방식입니다.

훅은 "에이전트를 믿지 않는다"는 뜻이 아닙니다. 실수할 수 있는 실행 환경을 인정하고, 위험한 경로를 구조적으로 좁히는 장치입니다.

메모리: 기억을 한 덩어리로 두지 않는 구조

AI 작업에서 메모리라는 단어는 너무 넓습니다. 저는 기억을 하나의 저장소로 보지 않고 목적별로 나눴습니다.

계층	저장하는 것	저장하지 않는 것
`MEMORY.md`	반복 실패, 사용자 교정, 다음 실행을 바꾸는 짧은 힌트	일반 지식, 긴 절차, 작업별 로그
지식 저장소	장기 보관할 개념, 조사, 설계 판단	실행 절차, 일회성 상태
실행 절차 / 런북	반복 가능한 운영 절차, 입력값, 검증, 정리 기준	단발성 메모
작업 증거	특정 작업의 계획, 실행 증거, 검증 결과	장기 지식 원본

예를 들어 "PR 본문에 오래된 브랜치 문맥이 남지 않게 확인하라"는 반복 교정은 pr-creator/MEMORY.md에 맞습니다. 반면 "Cloudflare Pages custom domain 연결 절차"는 런북에 맞습니다. "에이전트 실행 계층을 어떻게 나눌 것인가"는 장기 설계 문서에 가깝습니다.

이 기준을 두지 않으면 메모리는 금방 잡동사니가 됩니다. 다음 실행에 꼭 필요한 힌트와 언젠가 읽을 수도 있는 자료가 같은 곳에 섞이면 검색 품질도 떨어집니다.

에이전트와 스킬: 역할과 절차의 분리

제 구조에서 스킬과 에이전트는 다릅니다.

스킬은 메인 에이전트가 같은 문맥에서 따라야 하는 절차입니다. 예를 들어 git-committer, security-guide, systematic-debugging은 작업 방식과 검증 기준을 제공합니다.

에이전트는 독립 문맥이 이득인 전문 작업자입니다. 긴 탐색, 독립 리뷰, 보안 검토처럼 문맥을 분리하는 편이 나은 작업에서 씁니다.

스킬     = 같은 에이전트가 따라야 하는 절차
에이전트 = 독립 문맥으로 맡기는 전문 역할

이 둘을 나눈 이유는 단순합니다. 모든 것을 에이전트로 만들면 조율 비용이 커집니다. 반대로 모든 것을 스킬로만 두면 긴 탐색이나 독립 리뷰에서 문맥이 오염됩니다.

스웜, 에이전트 팀, 오케스트레이션

멀티 에이전트 구조를 설명할 때 스웜, 팀, 오케스트레이션이라는 말을 자주 씁니다. 제가 쓰는 구조는 스웜보다는 오케스트레이션에 가깝습니다.

방식	특징	잘 맞는 상황	부담
스웜	여러 에이전트가 중앙 조율 없이 작업을 넘기거나 공유 상태를 보고 움직임	작업이 독립적이고 각자 판단으로 충분할 때	결과 통합과 책임 추적이 어려울 수 있음
에이전트 팀	역할이 나뉜 에이전트를 병렬 또는 단계형 흐름으로 묶음	구현, 리뷰, 보안, QA처럼 책임이 분리될 때	각자 바꿀 범위와 합치는 순서를 관리해야 함
오케스트레이션	중앙의 메인 에이전트나 감독자가 목표, 위임, 증거, 최종 응답을 통합	작업 순서와 책임, 검증이 중요할 때	중앙 조율자가 병목이 될 수 있음

OpenAI Agents SDK 문서는 관리자 방식 흐름에서 메인 에이전트가 최종 책임을 유지하고 전문 에이전트를 도우미처럼 호출하는 방식을 설명합니다. AutoGen의 Swarm 문서는 중앙 조율자 없이 에이전트가 능력에 따라 작업을 넘기는 구조를 설명합니다. LangGraph의 감독자 패턴 문서는 중앙 감독자가 전문 작업자를 조율하는 형태를 설명합니다.

제 환경에서는 후자가 더 맞았습니다. 이유는 작업 산출물이 코드, 문서, PR, 배포, 증거로 이어지기 때문입니다. 단순히 멀티 에이전트가 답을 나눠 내는 것보다 누가 어떤 근거로 무엇을 바꿨고 어떤 검증을 했는지가 중요합니다.

그래서 기본은 오케스트레이션입니다.

목표
  -> 계획
  -> 스킬 선택
  -> 필요할 때 에이전트 위임
  -> 증거 수집
  -> 검증
  -> 최종 요약

에이전트 팀은 반복되는 협업 패턴이 생길 때만 만듭니다. 예를 들어 "구현 후 backend review, security review, infra review를 병렬로 돌리고 메인 에이전트가 종합한다" 같은 흐름이 반복되면 에이전트 팀 스킬로 승격할 수 있습니다. 그 전에는 명시적인 오케스트레이션이 더 단순합니다.

이 구조에서 중요한 운영 원칙

첫째, 새 계층을 쉽게 만들지 않습니다. wrapper script, alias, 오케스트레이션 계층은 반복되는 마찰이 확인된 뒤에만 만듭니다.

둘째, 도구별 설정 경로를 원본처럼 수정하지 않습니다. 각 도구의 설정 경로에 보이는 파일은 실제로는 공통 원본의 링크이거나 생성 결과일 수 있습니다. 원본은 공통 작업 공간입니다.

셋째, 지식과 실행 증거를 섞지 않습니다. 어떤 작업에서 무엇을 했는지는 작업 증거에 남기고, 다음에도 반복할 절차만 런북으로 승격합니다.

넷째, 훅은 강제 정책만 맡깁니다. "Django service는 어떻게 작성할 것인가" 같은 구현 기준은 훅이 아니라 스킬의 영역입니다. 훅은 위험 명령과 민감 파일 접근처럼 실행을 막아야 하는 것에 집중합니다.

마무리

이 구조의 목표는 AI 도구를 하나 더 잘 쓰는 것이 아닙니다. 도구가 바뀌어도 유지되는 작업 시스템을 만드는 것입니다.

Codex를 쓰든 Claude Code를 쓰든 같은 지침을 읽고, 같은 스킬을 쓰고, 같은 가드레일에 걸리고, 같은 메모리 체계를 따릅니다. 모델은 바뀔 수 있지만 작업 방식의 원본은 하나입니다.

아직 완성된 구조라기보다 계속 조정하는 운영 체계에 가깝습니다. 다만 기준은 분명합니다. 도구별 설정을 늘리는 대신, 도구 바깥에 내 작업 방식을 둡니다.