오늘의 AI 글: Claude Code 아키텍처에서 배우는 에이전트 설계

왜 이 글인가

오늘 고른 글은 Claude Code를 “잘 만든 AI 코딩 도구”가 아니라 “운영 가능한 에이전트 시스템”으로 해부한다는 점에서 읽을 가치가 크다. 요즘 AI 코딩 도구 이야기는 대개 모델 성능, 컨텍스트 길이, IDE 통합, 가격표, 벤치마크 점수로 흘러가기 쉽다. 물론 그런 요소도 중요하다. 하지만 실제 개발 현장에서 더 자주 부딪히는 문제는 모델이 코드를 쓸 수 있느냐가 아니다. 모델이 파일을 읽고, 명령을 실행하고, git을 만지고, 외부 도구를 호출하는 순간부터 생기는 권한, 감사 가능성, 실패 복구, 컨텍스트 붕괴가 진짜 문제다. 원문은 바로 이 “하네스(harness)”의 설계를 중심에 놓는다.

특히 흥미로운 지점은 Claude Code가 복잡한 멀티에이전트 스웜보다 단일 스레드 실행 루프와 평평한 히스토리를 우선한다는 해석이다. AI 에이전트 제품을 만들다 보면 병렬성, 자동 분해, 다중 역할 에이전트 같은 기능을 빨리 붙이고 싶어진다. 데모에서는 멋있어 보인다. 그러나 운영 환경에서는 누가 어떤 판단을 했는지 추적하기 어려운 시스템이 금방 부채가 된다. 원문은 Claude Code의 강점을 “더 많은 에이전트”가 아니라 “더 잘 보이는 루프”에서 찾는다. 이 관점은 AI 도구를 쓰는 사람뿐 아니라 직접 내부 에이전트 워크플로를 만들려는 팀에게도 유용하다.

지금 이 글이 중요한 또 다른 이유는 에이전트 안전성이 더 이상 부가 기능이 아니기 때문이다. 파일 읽기는 괜찮지만 파일 수정은 위험할 수 있다. 테스트 실행은 괜찮지만 임의의 shell 명령은 시스템 상태를 바꿀 수 있다. MCP 서버나 웹 검색 결과는 편리하지만, 외부 텍스트가 프롬프트 인젝션을 시도할 수도 있다. 원문은 Claude Code가 이런 문제를 모델의 선의에 맡기지 않고, 도구 호출과 권한 판단을 분리하는 구조로 다룬다고 설명한다. “모델이 똑똑하니 알아서 조심하겠지”가 아니라, 모델은 시도하고 시스템은 허용 여부를 판정하는 식이다.

또 하나의 장점은 원문이 확인된 사실과 커뮤니티 추론을 어느 정도 구분하려고 한다는 점이다. Claude Code의 내부 구현은 공개 문서만으로 전부 알 수 없다. 원문은 Anthropic 문서, 사용자 경험, 커뮤니티 분석, 소스맵 노출 보도 등을 섞어 설명하되, 일부 세부 명칭이나 내부 메커니즘은 검증되지 않았다고 표시한다. 이 태도는 AI 시대의 기술 글을 읽을 때 꽤 중요하다. 그럴듯한 아키텍처 다이어그램이 곧 공식 사실은 아니다. 따라서 이 글은 “Claude Code 내부를 완벽히 복원한 문서”라기보다, 공개적으로 관찰 가능한 제품 특성과 커뮤니티 분석을 바탕으로 에이전트 설계 원칙을 정리한 글로 읽는 편이 안전하다.

무엇보다 이 글은 특정 제품 칭찬을 넘어 일반화 가능한 질문을 던진다. 좋은 코딩 에이전트에는 어떤 경계가 필요한가? 컨텍스트가 길어질 때 무엇을 보존해야 하는가? 권한 승인 UI는 어디까지 자동화할 수 있는가? 서브에이전트는 언제 도움이 되고 언제 위험한가? 외부 도구 결과를 에이전트에게 다시 먹일 때 어떤 공격면이 생기는가? 이런 질문은 Claude Code, Codex, Cursor, OpenClaw, 사내 자동화 에이전트 모두에 적용된다. 그래서 오늘의 한 편으로 고를 만하다.

핵심 요약

• 원문의 핵심 주장은 “에이전트의 어려움은 모델보다 실행 하네스에 있다”는 것이다. 언어 모델은 계획을 세우고 코드를 생성할 수 있지만, 실제 환경에서 파일 시스템, shell, git, 네트워크, 외부 API를 다루려면 완전히 다른 종류의 설계가 필요하다. 이 설계가 약하면 모델이 아무리 좋아도 권한 오류, 컨텍스트 누수, 파괴적 명령, 추적 불가능한 실패가 반복된다.

• Claude Code는 plan-act-observe 루프를 중심으로 이해할 수 있다. 사용자의 요청을 받고, 모델이 다음 행동을 결정하고, 도구를 호출하고, 결과를 히스토리에 붙인 뒤 다시 모델을 호출한다. 도구 호출이 더 이상 없고 텍스트 응답만 나오면 루프가 멈춘다. 단순한 구조처럼 보이지만, 이 단순함 덕분에 전체 흐름을 읽고 디버깅하기가 쉬워진다.

• 원문은 Claude Code의 계층을 UI, 에이전트 코어, 도구 계층, 서브에이전트 계층, 권한·안전 계층, 모델 계층으로 나누어 설명한다. 중요한 것은 책임 분리다. 모델은 무엇을 시도할지 제안하고, 권한 계층은 허용 여부를 판단하며, 도구 계층은 실제 실행을 담당한다. 한 덩어리로 섞이면 빠르게 만들 수는 있지만 안전하게 운영하기 어렵다.

• 평평한 메시지 히스토리는 약점이 아니라 감사 로그에 가깝다. 모든 사용자 요청, 모델 응답, 도구 호출, 도구 결과가 순서대로 남기 때문에 문제가 생겼을 때 어느 지점에서 판단이 틀어졌는지 추적할 수 있다. 복잡한 병렬 상태 머신보다 성능은 덜 화려할 수 있지만, 실무에서는 “왜 이런 일이 일어났는가”를 설명할 수 있다는 점이 큰 장점이다.

• 컨텍스트 관리는 가장 까다로운 부분 중 하나다. 프로젝트 규칙을 담은 CLAUDE.md 같은 파일은 세션 초기에 중요한 기준점이 되지만, 작업이 길어지면 히스토리가 커지고 요약·압축이 필요해진다. 이때 중요한 지침이 희석되거나 빠질 수 있다. 원문은 실제 사용자들이 긴 세션에서 프로젝트 지침이 무시되는 현상을 보고했다는 점을 언급한다.

• 도구 호출은 권한 게이트를 거쳐야 한다. 읽기 전용 작업은 비교적 안전하게 자동 승인할 수 있지만, 파일 수정, shell 실행, git 작업, 네트워크 접근은 위험도가 다르다. 원문은 Claude Code가 읽기 작업, 상태 변경 작업, 고위험 작업을 구분하는 deny-first 모델을 취한다고 설명한다. “안전한 것은 지나가고, 위험한 것은 묻는다”가 아니라 “기본적으로 막고, 조건을 만족할 때만 연다”에 더 가깝다.

• 서브에이전트는 무제한 병렬 스웜이 아니라 통제된 병렬성으로 봐야 한다. 원문에 따르면 Claude Code는 특정 하위 작업을 별도 컨텍스트에서 처리하는 서브에이전트 패턴을 지원하지만, 깊이 제한과 격리된 컨텍스트가 중요하다. 무한히 하위 에이전트를 낳는 구조는 비용, 추적성, 안전성 모두에서 위험하다.

• MCP 통합은 강력하지만 공격면도 넓힌다. MCP 서버는 내부 API, 문서, 데이터베이스, 업무 도구를 에이전트에 연결할 수 있게 해준다. 하지만 MCP 결과도 결국 모델이 읽는 텍스트다. 악의적이거나 오염된 외부 결과가 “이전 지시를 무시하라” 같은 프롬프트 인젝션을 포함할 수 있다. 따라서 외부 도구 결과는 신뢰된 지시가 아니라 비신뢰 데이터로 취급해야 한다.

• 원문의 결론은 복잡성보다 제약의 가치에 가깝다. Claude Code가 흥미로운 이유는 모든 것을 자동화해서가 아니라, 모델·도구·권한·컨텍스트·서브에이전트 사이의 경계를 비교적 명확히 둔다는 점이다. 좋은 에이전트 시스템은 똑똑한 모델 하나로 완성되지 않는다. 행동할 수 있는 시스템일수록 멈출 수 있는 구조, 설명할 수 있는 로그, 제한할 수 있는 권한이 필요하다.

원문의 논지를 단계별로 풀어보기

첫 번째 단계는 문제 정의다. 원문은 코딩 에이전트를 단순한 코드 생성기가 아니라 상태와 부작용을 가진 실행 시스템으로 본다. 자동완성 도구는 잘못된 코드를 제안해도 사용자가 선택하지 않으면 그만이다. 하지만 에이전트는 파일을 고치고, 명령을 실행하고, 테스트를 돌리고, git 상태를 바꿀 수 있다. 이 순간부터 실패의 모양이 달라진다. 틀린 답변보다 더 위험한 것은 “틀린 행동”이다.

두 번째 단계는 실행 루프다. 에이전트는 한 번 답하고 끝나는 채팅이 아니라 반복 루프를 돈다. 모델이 현재 히스토리를 보고 다음 액션을 선택한다. 액션이 도구 호출이면 권한 검사를 거쳐 실행되고, 실행 결과가 다시 히스토리에 붙는다. 그 결과를 본 모델은 다음 행동을 결정한다. 이 패턴은 간단하지만 강력하다. 코딩 작업 대부분은 한 번에 끝나지 않기 때문이다. 파일을 읽고, 가설을 세우고, 수정하고, 테스트하고, 실패 로그를 보고, 다시 수정하는 반복이 필요하다.

세 번째 단계는 단일 스레드와 평평한 히스토리의 선택이다. 멀티에이전트 시스템은 이론적으로 더 빠르고 더 다양하게 탐색할 수 있다. 그러나 병렬 실행이 많아질수록 상태가 흩어지고, 결정의 출처가 불분명해지고, 실패를 재현하기 어려워진다. 원문은 Claude Code가 기본적으로 하나의 읽을 수 있는 실행 흐름을 유지한다는 점을 높게 본다. 이는 성능 최적화보다 운영 가능성을 우선하는 선택이다.

네 번째 단계는 컨텍스트의 두 종류를 구분하는 것이다. 하나는 세션 시작 때 로드되는 프로젝트 지식이다. 예를 들어 CLAUDE.md에는 코딩 규칙, 아키텍처 원칙, 테스트 방식, 금지된 패턴이 들어갈 수 있다. 다른 하나는 세션 중 쌓이는 작업 히스토리다. 에이전트는 이 둘을 함께 보고 판단하지만, 컨텍스트 창은 유한하다. 장기 작업에서는 요약이 필요하고, 요약은 언제나 손실을 만든다. 그래서 좋은 에이전트 환경은 “무엇을 압축할 것인가”뿐 아니라 “무엇은 절대 잃으면 안 되는가”를 설계해야 한다.

다섯 번째 단계는 도구 계층이다. 원문에서 가장 실무적인 대목은 “에이전트가 파일 시스템 접근권을 가진다”는 표현을 경계하는 부분이다. 더 정확히는 모델이 Read, Edit, Bash, Git, Web, MCP 같은 제한된 도구를 호출할 수 있고, 각 도구는 별도의 입력 검증과 권한 체크를 거쳐야 한다. 이 차이는 크다. 전자는 막연한 권한 부여이고, 후자는 감사 가능한 인터페이스다. 내부 에이전트를 만들 때도 도구를 “편한 함수 모음”이 아니라 “보안 경계”로 설계해야 한다.

여섯 번째 단계는 권한 모델이다. 읽기 전용 명령과 상태 변경 명령을 같은 수준으로 취급하면 곤란하다. 디렉터리 목록을 보는 것과 파일을 삭제하는 것은 전혀 다르다. 테스트 실행과 외부 서버로 데이터를 보내는 명령도 위험도가 다르다. 원문은 Claude Code가 안전한 읽기, 확인이 필요한 변경, 명시적 승인이 필요한 고위험 작업을 구분한다고 설명한다. 특히 흥미로운 점은 자동 승인 모드에서도 별도의 분류기가 사용자 요청과 도구 호출을 보고 판단한다는 설명이다. 모델이 자기 행동을 스스로 변호해서 권한을 얻는 구조를 피하려는 설계로 볼 수 있다.

일곱 번째 단계는 서브에이전트다. 서브에이전트는 긴 작업을 나눌 때 유용하다. 예를 들어 한쪽에서는 테스트 실패 원인을 조사하고, 다른 쪽에서는 문서와 기존 구현을 읽고, 메인 에이전트는 두 결과를 종합할 수 있다. 그러나 서브에이전트가 깊게 재귀하거나 서로에게 계속 일을 넘기면 비용과 복잡성이 폭발한다. 그래서 깊이 제한과 격리된 컨텍스트가 중요하다. “여러 에이전트가 일한다”보다 “어떤 경계 안에서 병렬화하는가”가 핵심이다.

여덟 번째 단계는 실행 중 조향이다. 실제 개발 작업에서는 처음 내린 지시가 항상 충분하지 않다. 에이전트가 작업하는 동안 사용자가 “그 방향 말고 테스트부터 봐줘” 또는 “이 파일은 건드리지 마”라고 끼어들 수 있어야 한다. 원문은 Claude Code가 실행 중 사용자의 새 입력을 다음 적절한 루프 지점에 반영하는 구조를 가진다고 설명한다. 이는 에이전트를 배치 작업이 아니라 협업 도구처럼 느끼게 만드는 중요한 요소다.

아홉 번째 단계는 MCP와 외부 통합이다. MCP는 에이전트에게 외부 도구와 데이터를 연결하는 표준 인터페이스로 자리 잡고 있다. 사내 문서, 이슈 트래커, 데이터베이스, 클라우드 도구를 연결하면 에이전트의 활용 범위는 크게 넓어진다. 하지만 연결이 늘어날수록 신뢰 경계도 복잡해진다. MCP 서버의 응답은 시스템 지시가 아니라 외부 데이터다. 이를 구분하지 못하면 에이전트는 도구 결과 안의 악성 문장을 지시로 오해할 수 있다.

열 번째 단계는 철학적 결론이다. 원문은 Claude Code의 설계를 “투명성과 통제 가능성을 위해 일부 병렬성과 자동화를 포기한 구조”로 본다. 이 결론이 설득력 있는 이유는 에이전트 시스템의 가치는 데모 순간보다 실패 순간에 드러나기 때문이다. 문제가 생겼을 때 무엇이 실행됐는지 확인할 수 있는가? 위험한 명령을 막을 수 있는가? 긴 작업 중 지침이 사라졌는지 알 수 있는가? 외부 도구 결과를 신뢰하지 않는 기본 자세가 있는가? 이런 질문에 답할 수 있어야 실제 업무에 맡길 수 있다.

일반 독자에게 중요한 포인트

• AI 에이전트는 “말 잘하는 챗봇”보다 “권한을 가진 자동화 시스템”에 가깝다. 그래서 답변 품질뿐 아니라 행동 범위, 승인 절차, 로그, 복구 방법이 중요하다. 에이전트가 내 컴퓨터나 회사 시스템에서 무엇을 할 수 있는지 모르면 편리함이 곧 위험이 될 수 있다.

• 좋은 자동화는 무조건 많이 하는 것이 아니라 적절히 멈출 수 있는 것이다. Claude Code의 권한 게이트 이야기가 중요한 이유도 여기에 있다. 안전한 읽기는 빠르게 허용하고, 위험한 변경은 사람에게 묻고, 고위험 작업은 더 강하게 제한하는 구조가 필요하다.

• “컨텍스트가 길다”는 말은 만능이 아니다. 긴 컨텍스트는 많은 정보를 넣을 수 있게 해주지만, 긴 작업에서는 무엇을 기억하고 무엇을 요약할지가 더 중요해진다. 프로젝트 규칙이 초반에만 있고 뒤에서 희미해진다면 에이전트는 점점 엉뚱한 결정을 내릴 수 있다.

• 여러 AI가 동시에 일하는 모습은 매력적이지만, 관리되지 않은 병렬성은 혼란을 만든다. 사람이 여러 동료와 일할 때도 역할, 범위, 보고 방식이 필요하듯이, 서브에이전트에도 범위와 종료 조건이 필요하다. 병렬화는 속도의 문제가 아니라 조율의 문제다.

• 외부 도구 연결은 편리함과 공격면을 동시에 늘린다. 캘린더, GitHub, Slack, 데이터베이스, 사내 문서가 연결되면 에이전트는 훨씬 유능해진다. 동시에 잘못된 데이터, 악성 문서, 오염된 도구 응답을 읽을 가능성도 생긴다. “외부에서 온 텍스트는 지시가 아니라 자료”라는 원칙이 중요하다.

• 앞으로 개발자의 역할은 코드 작성자에서 시스템 조율자로 조금씩 이동한다. 직접 모든 줄을 쓰는 시간은 줄 수 있지만, 좋은 작업 지시를 만들고, 위험한 권한을 판단하고, 결과를 검증하고, 실패 로그를 읽는 능력은 더 중요해진다. 에이전트 시대에도 판단력은 외주화되지 않는다.

적용 아이디어

• 프로젝트 루트에 에이전트용 운영 문서를 둔다. Claude Code의 CLAUDE.md처럼, 저장소별 규칙·금지 패턴·테스트 명령·배포 주의사항·코딩 스타일을 한 파일에 정리한다. 단순한 README와 달리 “에이전트가 작업 전에 반드시 읽어야 하는 기준 문서”로 관리하는 것이 좋다.

• 도구 권한을 세 등급으로 나눈다. 읽기 전용 작업, 상태를 바꾸는 작업, 고위험 작업을 구분해보자. 예를 들어 파일 읽기와 git status는 낮은 위험, 파일 수정과 테스트 실행은 중간 위험, 삭제·배포·외부 전송·권한 변경은 높은 위험으로 둔다. 팀 내부 자동화에서도 이 표를 먼저 만들면 사고를 줄일 수 있다.

• 에이전트 로그를 사람이 읽을 수 있게 남긴다. 단순히 최종 결과만 저장하지 말고, 어떤 파일을 읽었고 어떤 명령을 실행했고 어떤 실패를 만났는지 요약이 남아야 한다. 나중에 버그가 생겼을 때 “AI가 뭔가 했다”가 아니라 “이런 판단과 실행이 있었다”라고 추적할 수 있어야 한다.

• 긴 작업에는 중간 체크포인트를 강제한다. 에이전트에게 큰 기능 하나를 통째로 맡기기보다, 조사 요약, 계획, 첫 변경, 테스트 결과, 최종 diff 같은 단계로 끊는 편이 안전하다. 특히 컨텍스트가 길어지는 작업에서는 중간에 프로젝트 규칙과 목표를 재확인하게 하는 절차가 도움이 된다.

• 서브에이전트는 독립적인 탐색 작업에만 제한적으로 쓴다. “이 모듈의 테스트 실패 원인을 조사해줘”, “관련 문서를 찾아 요약해줘”, “대안 구현 방식을 비교해줘”처럼 결과가 요약으로 합쳐질 수 있는 일에 적합하다. 반대로 같은 파일을 여러 서브에이전트가 동시에 고치는 구조는 충돌과 혼란을 부른다.

• MCP나 외부 도구 결과를 비신뢰 데이터로 취급한다. 도구 응답 안의 문장을 시스템 지시처럼 사용하지 말고, 출처와 권한을 분리한다. 가능하면 MCP 서버는 최소 권한으로 실행하고, 파일 시스템 접근 범위를 제한하고, 민감 정보가 응답에 섞이지 않도록 필터링한다.

• 자동 승인 모드를 켜기 전에 실패 시나리오를 적어본다. 에이전트가 실수로 어떤 파일을 바꿀 수 있는지, 어떤 명령을 실행하면 곤란한지, 외부로 어떤 정보가 나가면 안 되는지 목록화한다. 그 목록이 없다면 자동화 수준을 낮추는 편이 낫다. 귀찮아 보여도 이 작업이 나중의 사고 대응 비용을 크게 줄인다.

• 결과 검토 기준을 diff만으로 제한하지 않는다. 최종 변경 파일, 테스트 결과, 남은 리스크, 롤백 방법, 의도적으로 하지 않은 일까지 함께 보게 하자. 에이전트가 만든 PR이나 패치를 검토할 때도 “코드가 맞는가”와 함께 “작업 범위가 지켜졌는가”를 확인해야 한다.

읽기 우선순위

AI 코딩 에이전트를 매일 쓰는 개발자, 사내 개발 자동화를 만들려는 플랫폼 팀, MCP나 내부 도구 연동을 고민하는 팀이라면 원문을 우선 읽을 만하다. 특히 Claude Code의 제품 사용법보다 “왜 이런 제약과 경계를 둬야 하는가”에 관심이 있다면 얻을 것이 많다.

다만 원문을 읽을 때는 모든 내부 구현 설명을 공식 사실로 받아들이기보다, 검증된 공개 문서와 커뮤니티 추론이 섞인 아키텍처 해설로 보는 것이 좋다. 공개적으로 확인된 동작과 추정된 세부 구현을 구분하며 읽으면 더 안전하다. 원문 전체를 읽을 시간은 없더라도, 실행 루프, 권한 모델, 컨텍스트 관리, MCP 공격면을 다룬 부분은 꼭 확인해볼 만하다. 오늘의 결론은 간단하다. 좋은 에이전트는 더 많은 일을 하는 시스템이 아니라, 무엇을 했는지 설명할 수 있고 위험한 순간에 멈출 수 있는 시스템이다.