Claude Code를 위한 '인지 아키텍처'라는 게 나왔는데, 텍스트 파일만으로 AI 에이전트의 사고방식을 설계한다고요?

AI 코딩 에이전트, 그냥 쓰면 되는 거 아닌가요?

요즘 Claude Code, Cursor, Copilot 같은 AI 코딩 도구를 쓰는 분들 많으시죠. 그런데 써보신 분들은 아실 거예요. 단순한 작업은 잘 해주는데, 좀 복잡한 프로젝트를 맡기면 맥락을 자꾸 잃어버리거나, 엉뚱한 방향으로 달려가는 경우가 꽤 있거든요. 프롬프트를 아무리 잘 써도 한계가 있다는 걸 느끼게 되는 순간이 옵니다.

이런 문제를 해결하려고 누군가가 재밌는 접근을 했어요. "인지 아키텍처(Cognitive Architecture)"라는 개념을 Claude Code에 적용한 건데요, 핵심은 놀랍게도 일반 텍스트 파일만으로 AI 에이전트의 사고 흐름을 체계적으로 설계하겠다는 거예요.

인지 아키텍처가 대체 뭔가요?

이름이 거창한데, 쉽게 말하면 이래요. 사람이 복잡한 일을 할 때 머릿속에서 "먼저 현황 파악하고 → 계획 세우고 → 하나씩 실행하고 → 중간에 점검하고 → 필요하면 계획 수정하고"라는 사고 흐름이 있잖아요. 이걸 AI 에이전트에게도 똑같이 적용하자는 거예요.

기존에 AI 코딩 도구를 쓸 때는 보통 CLAUDE.md 같은 설정 파일에 "이 프로젝트는 TypeScript로 되어 있고, 테스트는 Jest로 돌려" 정도의 정적인 정보를 넣어줬거든요. 그런데 이 인지 아키텍처는 한 단계 더 나가서, AI가 작업하는 과정 자체를 구조화하는 거예요.

구체적으로 보면, 프로젝트 루트에 여러 개의 마크다운 파일을 배치해요. 예를 들어 하나의 파일에는 "작업을 시작하기 전에 반드시 관련 코드를 먼저 읽어라", 다른 파일에는 "코드를 수정한 뒤에는 반드시 테스트를 돌려서 확인하라", 또 다른 파일에는 "에러가 나면 바로 고치지 말고 원인부터 분석하라" 같은 행동 규칙이 들어가는 식이에요. 이 파일들이 모여서 AI 에이전트가 따라야 할 "사고의 흐름도"를 만들어내는 거죠.

기존 방식과 뭐가 다른 건데요?

기존의 프롬프트 엔지니어링이나 시스템 프롬프트 방식은 "뭘 해라"를 알려주는 데 집중했어요. 반면 이 인지 아키텍처는 "어떻게 생각해라"를 알려주는 데 집중한다는 점이 달라요.

비유를 하나 들어볼게요. 기존 방식이 신입 개발자에게 "이 버그 고쳐줘"라고 업무를 던지는 거라면, 인지 아키텍처는 "먼저 재현부터 해보고, 로그를 확인하고, 관련 코드를 파악한 다음에 수정하고, 테스트까지 돌려봐"라고 일하는 방법 자체를 가르쳐주는 거예요. 당연히 후자가 더 안정적인 결과를 낼 가능성이 높겠죠.

또 하나 중요한 특징은, 이게 전부 일반 텍스트 파일이라는 거예요. 특별한 프레임워크나 SDK가 필요 없어요. 그냥 마크다운 파일을 프로젝트에 넣어두면 Claude Code가 그걸 읽고 따르는 구조예요. 덕분에 Git으로 버전 관리도 되고, 팀원끼리 공유하기도 쉽고, 다른 프로젝트에 복사해서 재사용하기도 편해요.

실제로 어떤 파일 구조인가요?

이 아키텍처는 보통 다음과 같은 구성을 가져요. 프로젝트 루트에 CLAUDE.md를 메인 진입점으로 두고, 여기서 다른 문서들을 참조하는 방식이에요. 예를 들면 작업 유형별로 "버그 수정 시 따를 절차", "새 기능 추가 시 따를 절차", "리팩토링 시 따를 절차" 같은 플레이북(playbook)을 만들어두는 거죠.

각 플레이북 안에는 단계별 체크리스트가 있어요. 단순히 "테스트를 돌려라"가 아니라, "어떤 상황에서 어떤 테스트를 돌려야 하고, 실패하면 어떻게 대응해야 하는지"까지 적혀 있어요. 이게 마치 시니어 개발자의 경험과 노하우를 문서화해서 AI에게 주입하는 것과 비슷해요.

업계에서 비슷한 시도들

사실 AI 에이전트의 행동을 구조화하려는 시도는 이게 처음이 아니에요. Anthropic 자체에서도 Claude Code의 CLAUDE.md 파일 시스템을 점점 고도화하고 있고, Cursor에도 .cursorrules 파일이 있죠. OpenAI의 Codex도 비슷한 맥락에서 에이전트의 작업 방식을 제어하는 기능을 발전시키고 있어요.

다만 이런 기존 도구들의 설정 파일은 대부분 "코딩 스타일 가이드" 수준에 머물러 있어요. 이 프로젝트가 차별화되는 지점은, 단순한 스타일 가이드를 넘어서 인지과학에서 빌려온 개념으로 에이전트의 전체 작업 사이클을 설계한다는 점이에요. 인식(Perception) → 계획(Planning) → 실행(Execution) → 반성(Reflection)이라는 루프를 명시적으로 만드는 거죠.

최근에는 Devin, SWE-Agent 같은 완전 자율형 코딩 에이전트도 등장하고 있는데, 이런 도구들이 내부적으로 사용하는 로직도 결국 비슷한 인지 아키텍처의 변형이에요. 차이점이라면 이 프로젝트는 그 로직을 사용자가 직접 편집할 수 있는 텍스트 파일로 꺼내놨다는 거예요.

한국 개발자라면 이렇게 활용해보세요

Claude Code를 이미 쓰고 계신다면, 당장 시도해볼 수 있는 것들이 있어요. 먼저 프로젝트의 CLAUDE.md에 작업 절차를 좀 더 구체적으로 적어보세요. "수정 전에 관련 테스트 먼저 확인", "PR 올리기 전에 lint 통과 확인" 같은 규칙을 명시하는 것만으로도 AI의 작업 품질이 눈에 띄게 올라가거든요.

팀 단위로 쓰기에도 좋아요. 팀의 코드 리뷰 기준이나 배포 절차를 마크다운으로 정리해서 넣어두면, AI가 그 팀의 문화와 규칙에 맞춰서 코드를 생성하게 할 수 있어요. 신입 온보딩 문서를 AI한테도 적용하는 셈이죠.

주의할 점도 있어요. 규칙을 너무 많이 넣으면 오히려 AI가 혼란스러워하거나 느려질 수 있어요. 컨텍스트 윈도우에도 한계가 있으니까요. 정말 중요한 핵심 원칙 위주로 간결하게 유지하는 게 좋아요.