AI 코딩 에이전트(AI coding agents)는 훨씬 더 유용해지고 있지만, 제가 계속 마주치는 한 가지 문제가 있습니다:

그들은 프로젝트 특화된 교훈(project-specific lessons)을 잊어버립니다.

모델이 나빠서가 아닙니다. 프롬프트(prompt)에 문단 하나가 부족해서도 아닙니다. 문제는 구조적인 것입니다.

대부분의 코딩 에이전트는 일시적인 대화 컨텍스트(conversation context) 내에서 작동합니다. 세션 동안 당신이 말하는 내용은 이해할 수 있지만, 일단 그 컨텍스트가 사라지면 똑같은 실수가 쉽게 다시 발생할 수 있습니다.

예를 들어:

• 에이전트가 소스 스키마(source schema)를 업데이트하는 대신 생성된 파일들을 수동으로 편집함
• 프로젝트가 스토어/서비스(stores/services)를 사용함에도 불구하고 비즈니스 로직(business logic)을 React 컴포넌트로 이동시킴
• 잘못된 테스트 명령어를 실행함
• 이전의 디버깅 결론을 무시함
• 지난주에 이미 실패했던 수정을 반복함
• 특정 폴더에 특별한 컨벤션(conventions)이 있다는 사실을 잊어버림

이는 개발자들이 에이전트에게 똑같은 말을 계속해서 반복해야 하는 이상한 워크플로(workflow)를 만듭니다.

어느 시점에는 "이것을 기억해 주세요"라는 요청이 프로젝트 자체의 일부가 되어야 합니다.

명확한 해결책: 교훈 파일 (a lessons file)

간단한 아이디어는 다음과 같은 것을 만드는 것입니다:

LESSONS.md

• 생성된 GraphQL 타입을 수동으로 편집하지 마세요.
• 비즈니스 로직에는 MobX 스토어를 사용하세요.
• 결제 로직을 변경하기 전에 pnpm test:unit을 실행하세요.
• src/generated/ 내의 파일들을 수정하지 마세요.

이것은 이미 아무것도 없는 것보다는 낫습니다.

이는 암묵적인 프로젝트 지식을 명시적으로 만듭니다. Git에서 버전 관리가 가능하며, 서로 다른 에이전트들이 읽을 수 있습니다.

하지만 이 아이디어를 가지고 작업하면서, 저는 단순한 파일만으로는 충분하지 않다는 느낌을 받기 시작했습니다.

문제는 교훈을 저장하는 것이 아닙니다.

문제는 적절한 순간에 적절한 교훈을 검색(retrieving)하는 것입니다.

단순한 교훈 파일이 확장성(scale)을 갖기 어려운 이유

평면적인 마크다운(markdown) 파일은 교훈이 5개일 때는 잘 작동합니다.

하지만 교훈이 50개, 100개, 또는 수백 개가 되면 훨씬 덜 유용해집니다.

몇 가지 문제들이 빠르게 나타납니다:

1. 파일이 노이즈(noisy)가 됨

에이전트가 너무 많은 무관한 컨텍스트를 읽을 수 있습니다.

에이전트가 CSS를 수정하고 있을 때, GraphQL 코드 생성에 관한 레슨(lesson)은 유용하지 않습니다.

README를 변경하고 있을 때, 결제 검증(payment validation)에 관한 레슨은 유용하지 않습니다.

모든 에이전트가 매번 모든 레슨을 읽는다면, 메모리는 노이즈(noise)가 됩니다.

1. 레슨이 컨텍스트를 잃음

다음과 같은 레슨은 기술적으로는 정확합니다:

생성된 파일(generated files)을 수동으로 편집하지 마세요.

하지만 중요한 컨텍스트가 누락되어 있습니다:

• 어떤 파일들이 생성되는가?
• 어떤 명령어가 그것들을 다시 생성하는가?
• 무엇이 원래의 실수를 유발했는가?
• 이것은 어떤 규칙과 관련이 있는가?
• 이것은 항상 적용되는가, 아니면 특정 패키지에만 적용되는가?
• 이것이 여전히 최신 정보인가?

레슨은 존재하지만, 코드베이스(codebase)와 단절되어 있습니다.

2. 레슨이 오래됨 (stale)

프로젝트는 진화합니다.

명령어가 변경됩니다.

폴더 이름이 바뀝니다.

아키텍처 규칙(architectural rule)이 교체됩니다.

단순한 파일만으로는 해당 레슨이 최신인지, 구식인지, 아니면 부분적으로만 유효한지를 거의 알려주지 못합니다.

3. 에이전트가 관계를 쉽게 추론할 수 없음

실제 프로젝트에서 지식은 서로 연결되어 있습니다.

실수는 다음과 연결될 수 있습니다:

• 파일 경로
• 명령어
• 아키텍처 규칙 (architectural rule)
• 도구 (tool)
• 패키지 (package)
• 도메인 영역 (domain area)
• 이전에 실패한 수정 사항
• 다른 레슨

평면적인 파일(flat file)은 이러한 관계를 잘 나타내지 못합니다.

이것이 제가 레슨을 그래프(graph)로 생각하기 시작한 이유입니다.

그래프 기반 레슨 (Graph-based lessons)

그래프 기반 레슨 시스템은 레슨을 고립된 노트가 아니라, 연결된 프로젝트 지식의 조각으로 취급합니다.

다음과 같은 방식 대신:

생성된 GraphQL 타입을 수동으로 편집하지 마세요.

다음과 같이 모델링할 수 있습니다:

레슨:
생성된 GraphQL 타입을 수동으로 편집하지 마세요.
대신 스키마(schema)를 업데이트하고 codegen을 실행하세요.
연결된 컨텍스트:
영향을 받는 파일:

• src/generated/graphql/*
• packages/api/generated/*
  명령어:
• pnpm codegen
  관련 규칙:
• 생성된 파일은 읽기 전용임
  실수 유형:
• 생성된 출력물의 수동 편집
  도메인:
• GraphQL
• API 타입
  최신성:
• 최근 확인됨

이제 레슨은 더 이상 단순한 텍스트가 아닙니다.

레슨은 관계를 가집니다.

에이전트가 src/generated/graphql/User.ts를 수정하기 전에, 해당 경로와 연결된 레슨(lessons)을 검색할 수 있습니다.

결제 검증(payment validation) 로직을 변경하기 전에, 결제 도메인(payment domain)과 연결된 레슨을 검색할 수 있습니다.

테스트를 실행하기 전에, 현재 패키지(package)와 연결된 올바른 명령어를 검색할 수 있습니다.

이는 개발자들이 실제로 프로젝트 지식을 기억하는 방식에 더 가깝습니다.

우리는 모든 것을 하나의 거대한 문서로 기억하지 않습니다. 우리는 연결 관계를 기억합니다:

“이 파일은 생성된(generated) 파일이다.”

“이 폴더는 결제 도메인에 속한다.”

“저 명령어는 이전에 실패했었다.”

“저 컨벤션(convention)은 저번 프로덕션 버그 때문에 존재한다.”

유용한 에이전트 메모리 시스템도 이와 동일하게 작동해야 합니다.

레슨에는 무엇이 포함되어야 할까요?

레슨은 아마도 단순한 한 문장 이상의 것을 포함해야 할 것입니다.

예를 들어:

레슨 (Lesson):
비즈니스 로직(Business logic)은 React 컴포넌트가 아니라 MobX 스토어(stores)에 머물러야 합니다.
이유 (Reason):
이 프로젝트는 도메인 로직(domain logic)을 UI 렌더링으로부터 분리합니다.
로직을 컴포넌트로 옮기면 테스트와 재사용이 더 어려워집니다.
적용 대상 (Applies to):

• src/stores/*
• src/features/*
  관련 개념 (Related concepts):
• MobX
• 도메인 로직 (domain logic)
• React 컴포넌트 (React components)
• 관심사 분리 (separation of concerns)
  실수 유형 (Mistake type):
• 아키텍처 위반 (architectural violation)
  권장 동작 (Suggested behavior): 만약 변경 사항에 비즈니스 로직이 필요하다면, 먼저 스토어/서비스 레이어(store/service layer)에 추가하세요. React 컴포넌트는 가급적 선언적(declarative)으로 유지하세요.

이렇게 하면 에이전트가 단순히 규칙을 읽는 것을 넘어, 올바르게 행동할 수 있는 충분한 정보를 얻게 됩니다.

인간의 기억 vs 에이전트의 기억

한 가지 중요한 질문은 다음과 같습니다:

에이전트가 자동으로 레슨을 생성하도록 허용해야 할까요?

제 생각에 답은 '예, 하지만 주의해서'입니다.

예를 들어, 변경에 실패한 후 에이전트는 다음과 같은 제안을 할 수 있습니다:

제안된 레슨 (Proposed lesson):
이 저장소(repository)에서 npm을 사용하지 마세요. 이 프로젝트는 pnpm을 사용합니다.
근거 (Evidence):
npm install이 package-lock.json을 생성하여 의존성 일관성(dependency consistency)을 깨뜨렸습니다.
제안된 범위 (Suggested scope):
전체 저장소 (whole repository)
관련 명령어 (Related command):
pnpm install

하지만 저는 모든 에이전트가 검토 없이 영구적으로 레슨을 작성하는 것을 원하지는 않습니다.

더 나은 워크플로우는 다음과 같을 수 있습니다:

1. 에이전트가 재사용 가능한 레슨 (lesson)을 감지합니다.
2. 에이전트가 해당 레슨을 제안합니다.
3. 사람이 이를 승인, 수정 또는 거부합니다.
4. 승인된 레슨은 저장소 (repository)의 일부가 됩니다.
5. 향후 에이전트들은 관련이 있을 때 이를 검색 (retrieve)할 수 있습니다.

이렇게 하면 메모리가 통제되지 않는 노이즈 (noise)로 변하지 않으면서도 유용하게 유지될 수 있습니다.

여러 코딩 에이전트를 사용할 때 이것이 더 중요한 이유

이제 많은 개발자가 하나 이상의 AI 코딩 도구를 사용합니다.

예를 들어:

• Claude Code
• Cursor
• Codex CLI
• GitHub Copilot
• Gemini CLI
• Aider
• Roo
• Cline
• Windsurf

각 도구는 자신만의 설정 (configuration) 스타일을 가지고 있습니다.

어떤 도구는 마크다운 (markdown) 지침 파일을 사용합니다.

어떤 도구는 규칙 (rules)을 사용합니다.

어떤 도구는 명령 (commands)을 사용합니다.

어떤 도구는 MCP를 지원합니다.

어떤 도구는 자체적인 프로젝트 설정 (project config) 구조를 가지고 있습니다.

이는 또 다른 문제, 즉 프로젝트 지식의 파편화 (fragmented)를 야기합니다.

CLAUDE.md에는 하나의 규칙이 있고, .cursor/rules에는 또 다른 규칙이 있으며, AGENTS.md에는 또 다른 규칙이, 그리고 특정 도구 전용 설정에는 또 다른 규칙이 있을 수 있습니다.

결국, 당신의 에이전트들은 프로젝트에 대해 동일한 이해를 바탕으로 작동하지 않게 됩니다.

그것이 바로 제가 AgentsMesh를 통해 해결하고자 하는 더 넓은 범위의 문제입니다.

AgentsMesh란 무엇인가?

AgentsMesh는 하나의 정전 (canonical) 소스로부터 AI 코딩 어시스턴트 설정을 관리하기 위한 오픈 소스 CLI/라이브러리입니다.

아이디어는 간단합니다:

.agentsmesh/ 디렉토리에 프로젝트 지식을 한 번 정의하면, 다양한 AI 코딩 도구들을 위한 네이티브 설정 파일을 생성합니다.

AgentsMesh는 다음과 같은 것들을 관리할 수 있습니다:

• 규칙 (rules)
• 명령 (commands)
• 에이전트 (agents)
• 기술 (skills)
• 훅 (hooks)
• 권한 (permissions)
• MCP 서버 (MCP servers)
• 무시 패턴 (ignore patterns)
• 그래프 기반 레슨 (graph-based lessons)

레슨 (lessons) 시스템은 제가 가장 흥미롭다고 생각하는 부분입니다.

이는 단순한 메모로 가득 찬 파일이 아니라, 구조화되고 연결된 메모리로 설계되었습니다.

목표는 단순히 지침을 저장하는 것이 아닙니다.

목표는 에이전트가 적절한 시점에 적절한 프로젝트 지식을 검색할 수 있도록 돕는 것입니다.

워크플로우 예시

에이전트가 실수를 한다고 가정해 봅시다.

에이전트가 생성된 GraphQL 타입을 수동으로 수정했습니다.

로컬 빌드는 통과했지만, 나중에 코드 생성 (codegen) 과정에서 해당 변경 사항이 덮어씌워집니다.

채팅창에 단순히 다음과 같이 말하는 대신:

다시는 그렇게 하지 마세요.

프로젝트는 다음과 같은 교훈 (lesson)을 기록할 수 있습니다:

교훈 (Lesson):
생성된 GraphQL 타입을 수동으로 편집하지 마세요.
대신 스키마 (schema)를 업데이트하고 타입을 다시 생성하세요.
연결된 파일:

• src/generated/graphql/*
• packages/api/generated/*
  명령어 (Command): pnpm codegen
  관련 규칙 (Related rule): 생성된 파일은 읽기 전용 (read-only)임
  실수 유형 (Mistake type): 생성된 출력물을 편집함

나중에 다른 에이전트가 src/generated/graphql/ 내부의 파일을 편집하려고 합니다.

변경을 수행하기 전에, 해당 경로와 연결된 교훈을 검색할 수 있습니다.

에이전트는 프로젝트의 모든 지침을 읽을 필요가 없습니다.

관련된 메모리 (memory)만 있으면 됩니다.

진정한 과제: 잘못된 메모리 방지

장기 메모리 (long-term memory)는 유용해 보이지만, 잘못된 메모리는 메모리가 없는 것보다 더 나쁠 수 있습니다.

교훈 시스템에는 안전장치가 필요합니다.

제가 여전히 고민 중인 몇 가지 질문들:

교훈의 유효 기간이 있어야 할까요?

일부 교훈은 아마도 자동으로 오래된 것 (stale)이 되어야 할 것입니다.

예를 들어, 명령어가 다음과 같이 변경될 수 있습니다:

pnpm test

에서:

pnpm test:unit

로 말이죠.

만약 오래된 교훈이 영원히 남아 있다면, 에이전트는 구식 지침을 따를 수도 있습니다.

모든 교훈에 승인이 필요해야 할까요?

완전 자동화된 메모리는 노이즈 (noisy)가 심해질 수 있습니다.

하지만 모든 교훈에 대해 수동 승인을 요구하는 것은 너무 많은 마찰 (friction)을 일으킬 수 있습니다.

좋은 시스템은 다음과 같이 서로 다른 신뢰 수준 (trust levels)이 필요할 수 있습니다:

• 제안됨 (proposed)
• 승인됨 (approved)
• 사용 중단됨 (deprecated)
• 보관됨 (archived)

과적합 (overfitting)을 어떻게 방지할 것인가?

한 번의 실패한 상호작용이 항상 일반적인 규칙이 존재함을 의미하지는 않습니다.

만약 에이전트가 한 번의 잘못된 변경을 수행했다고 해서, 교훈이 반드시 다음과 같이 되어야 하는 것은 아닙:

이 파일은 절대 건드리지 마세요.

유용한 교훈은 단 한 번의 실수에서 오는 두려움이 아니라, 실제 재사용 가능한 원칙을 포착해야 합니다.

컨텍스트 (context)는 어느 정도가 적당할까요?

컨텍스트가 너무 적으면 교훈이 모호해집니다.

컨텍스트가 너무 많으면 비용이 많이 들고 노이즈가 심해집니다.

이상적인 교훈은 작고, 구체적이며, 프로젝트의 적절한 부분들과 연결되어 있어야 합니다.

그래프 기반 메모리 (graph-based memory)를 탐구할 가치가 있다고 생각하는 이유

프롬프트 파일 (prompt files)은 유용합니다.

규칙 (rules)은 유용합니다.

문서화 (documentation)는 유용합니다.

하지만 AI 코딩 에이전트에게는 “모든 작업 전에 이 거대한 지침 파일을 읽으세요”라는 방식보다 더 정밀한 무언가가 필요합니다.

그들에게는 문맥적 회상 (contextual recall)이 필요합니다.

생성된 파일을 편집할 때는 코드 생성 (codegen) 교훈을 회상해야 합니다.

결제 로직을 건드릴 때는 결제 관련 교훈을 회상해야 합니다.

아키텍처를 변경할 때는 아키텍처 제약 사항 (architectural constraints)을 회상해야 합니다.

명령어를 실행할 때는 올바른 패키지 매니저 (package manager)와 테스트 스크립트를 회상해야 합니다.

이것이 제가 그래프 기반의 프로젝트 메모리 (graph-based project memory)가 유망한 방향이라고 생각하는 이유입니다.

그래프가 유행이기 때문이 아닙니다.

소프트웨어 프로젝트는 이미 그래프이기 때문입니다:

• 파일은 파일에 의존합니다
• 명령어는 패키지에 영향을 미칩니다
• 규칙은 디렉토리에 적용됩니다
• 실수는 도메인 (domains)에서 발생합니다
• 컨벤션 (conventions)은 아키텍처와 연관됩니다
• 수정 사항은 이전 버그와 연관됩니다

에이전트 메모리는 그러한 구조를 반영해야 합니다.

마치며

저는 AI 코딩 에이전트의 미래가 단순히 더 큰 컨텍스트 윈도우 (context windows)에 있다고 생각하지 않습니다.

더 큰 컨텍스트가 도움이 되기는 하지만, 모든 것을 해결해주지는 않습니다.

진정한 개선은 더 나은 프로젝트 메모리로부터 올 수 있습니다:

• 구조화된 (structured)
• 버전 관리되는 (versioned)
• 검토 가능한 (reviewable)
• 코드베이스와 연결된 (connected to the codebase)
• 관련성에 따라 검색 가능한 (retrievable by relevance)
• 도구 간에 공유되는 (shared across tools)

이것이 제가 AgentsMesh에서 실험하고 있는 것입니다.

핵심 아이디어는 간단합니다:

에이전트가 프로젝트 특유의 동일한 실수를 영원히 반복해서는 안 된다는 것입니다.

실수가 유용한 무언가를 가르쳐줄 때, 그 교훈은 프로젝트의 일부가 되어야 합니다.

GitHub: https://github.com/sampleXbro/agentsmesh

AI 코딩 에이전트로 개발 중인 개발자분들의 피드백을 간절히 기다립니다:

에이전트가 노이즈가 심해지거나, 오래되거나, 과하게 설계(over-engineered)되지 않으면서도 반복되는 실수를 피할 수 있도록 돕는 장기적인 프로젝트 메모리를 어떻게 설계하시겠습니까?