제13장 Knowledge Base: 에이전트가 학습하는 구조

지난 장에서 우리는 일을 잘게 나누는 법을 봤다. 큰 기능을 통째로 던지지 말고, 경계와 완료 기준이 선명한 작업으로 쪼개야 에이전트가 덜 헤맨다는 이야기였다. 그런데 여기서 한 가지 질문이 남는다. 그렇게 잘 쪼갠 작업을 매번 처음부터 다시 설명해야 한다면, 과연 팀의 속도는 얼마나 빨라질까?

처음 한두 번은 괜찮다. 하지만 세 번째부터는 피곤해진다. "우리는 폼 검증을 이렇게 한다", "이 프로젝트에서는 이 라이브러리를 선호하지 않는다", "이 레이어에서는 직접 DB를 건드리지 않는다", "UI 수정이면 스크린샷까지 남겨 달라" 같은 말을 계속 반복하게 된다. 그 순간 깨닫게 된다. 이건 대화가 아니라, 아직 문서화되지 않은 팀의 기억이라는 사실을.

Antigravity의 Knowledge Items는 바로 이 지점을 겨냥한다. 공식 문서에 따르면 Knowledge Items는 코딩 세션에서 나온 중요한 통찰, 패턴, 해결책을 자동으로 포착하고 정리하는 지속 기억 시스템이다.¹ 한마디로 말해, 대화에서 흘러가던 맥락을 다시 꺼내 쓸 수 있는 자산으로 바꾸는 장치다.

좋은 Knowledge Base가 생기면 에이전트는 더 이상 매번 신입사원처럼 행동하지 않는다. 같은 팀에서 몇 달 일한 사람처럼 말투와 판단이 안정된다. 반대로 이 구조가 없으면, 아무리 좋은 모델을 써도 매 세션마다 "우리 팀은 원래 이렇게 해요"를 다시 가르쳐야 한다.

기억이 없는 에이전트는 매번 신입이다

에이전트가 똑똑해 보이다가도 갑자기 엉뚱한 선택을 하는 이유는 의외로 단순하다. 모르는 상태에서 합리적으로 추측했기 때문이다.

예를 들어 당신의 팀은 다음과 같은 암묵지를 갖고 있다고 해보자. 프런트엔드 폼은 react-hook-form과 zod 조합을 쓴다. 서버 상태는 React Query로 다루고, 전역 상태는 꼭 필요할 때만 쓴다. 날짜 처리는 특정 유틸로 통일한다. 새로운 패키지는 가볍게 추가하지 않는다. API 응답 형식은 실패 케이스까지 공통 래퍼를 유지한다.

이 사실을 에이전트가 모르면 어떻게 될까. 폼마다 다른 검증 방식을 섞고, 이미 있는 유틸 대신 새 라이브러리를 넣고, 라우트 핸들러에서 비즈니스 로직을 직접 처리하고, 에러 응답 형식을 제멋대로 바꿔 버릴 수 있다. 모두 "코드가 돌아가게 만들려는" 선의에서 나온 선택이다. 문제는 그 선의가 팀의 방식과 다르다는 데 있다.

그래서 Knowledge Base의 핵심 가치는 단순한 기억 저장이 아니다. 추측의 범위를 줄이는 것이다. 팀이 중요하게 여기는 선택지를 미리 좁혀 주면, 에이전트는 덜 창의적이지만 훨씬 더 유용해진다.

그리고 이것은 개인 생산성의 문제가 아니라 팀 운영의 문제이기도 하다. 개인이 발견한 좋은 프롬프트와 운영법이 휘발되지 않고 팀의 자산으로 축적되어야 조직 전체의 AI 활용 수준이 올라간다는 점은 여러 실무 글에서도 반복해서 강조된다.² 잘 쓰는 한 사람의 요령이 아니라, 모두가 재사용할 수 있는 구조가 필요하다는 뜻이다.

Knowledge Base에는 무엇을 넣어야 하는가

Knowledge Base를 처음 만들 때 많은 사람이 이렇게 생각한다. "좋은 팁을 다 넣으면 되겠지?" 그런데 그렇게 시작하면 금방 잡동사니 창고가 된다. 핵심은 정보의 양이 아니라, 반복해서 다시 설명하게 되는 종류의 정보를 담는 것이다.

실무에서 특히 가치가 큰 지식은 대체로 네 부류다.

• 코드 컨벤션: 네이밍, 파일 구조, 테스트 스타일, 주석 규칙, 타입 작성 방식처럼 일관성이 중요한 항목

• 기술 선호와 금지사항: 어떤 라이브러리를 우선 선택하는지, 어떤 패턴은 피하는지, 새 의존성을 추가할 때 기준이 무엇인지

• 아키텍처 결정: 어디서 어떤 책임을 지는지, 어떤 레이어는 무엇을 하면 안 되는지, 예외 처리는 어느 층에서 모으는지 같은 구조적 원칙

• 검증과 리뷰 습관: UI 변경 시 스크린샷을 남길지, 브라우저 검증을 언제 돌릴지, 어떤 변경은 반드시 테스트까지 포함해야 하는지 같은 완료 습관

이 네 가지가 중요한 이유는 간단하다. 이것들이야말로 에이전트가 혼자 판단하기 가장 어려운 영역이기 때문이다. 문법은 모델이 잘 안다. 하지만 "우리 팀이 무엇을 좋아하고 싫어하는가"는 코드 몇 파일만 읽고는 완전히 이해하기 어렵다.

여기서 기억해야 할 점이 하나 있다. Knowledge Base는 백과사전이 아니다. 저장소 전체 설명서를 다 옮겨 적는 곳이 아니라, 에이전트의 선택을 바꾸는 정보를 넣는 곳이다. 읽어도 행동이 안 바뀌는 문장은 대개 지식이 아니라 배경 설명에 가깝다.

규칙, 워크플로우, 스킬, AGENTS.md, Knowledge Base는 어떻게 다른가

이쯤 되면 개념이 조금 헷갈릴 수 있다. 규칙도 있고, 워크플로우도 있고, 스킬도 있고, AGENTS.md도 있고, 또 Knowledge Base도 있다. 이름이 많아 보이지만 역할을 나눠 보면 오히려 깔끔하다.

커뮤니티 가이드들이 공통으로 설명하는 구분을 빌리면, Rules는 "항상 지켜야 하는 것", Workflows는 "내가 호출하면 실행하는 절차", Skills는 "특정 상황에서 불러올 전문 지식"에 가깝다.³ 여기에 Knowledge Base를 더하면 "반복 작업과 피드백 속에서 축적되는 지속 기억", AGENTS.md를 더하면 "저장소 루트에 두는 사람이 읽을 수 있는 프로젝트 운영 지침서"라고 이해하면 쉽다.⁴

이 차이를 실무적으로 풀어보자.

Rules는 헬멧이다. 항상 쓴다. 예를 들어 "비밀키를 하드코딩하지 말 것", "공개 함수에는 타입 힌트를 붙일 것" 같은 규칙은 작업 종류와 상관없이 적용된다.

Workflows는 버튼이다. 예를 들어 /generate-tests 같은 명령을 호출했을 때만 특정 절차가 실행된다. 자주 하는 작업을 빠르게 반복하기 위한 장치다.

Skills는 전문가 카드다. 보안 검토, 마이그레이션 설계, 컴포넌트 생성처럼 특정 분야의 지식 묶음을 필요할 때 로드한다.

AGENTS.md는 팀 안내문이다. 이 저장소에서 에이전트가 먼저 읽어야 할 기술 스택, 금지사항, 선호 패턴, 자주 쓰는 명령을 한곳에 정리해 둔다.

Knowledge Base는 그 사이를 잇는 살아 있는 메모리다. 작업과 피드백이 반복되면서 "이 팀은 이렇게 판단한다"는 패턴을 점점 축적한다.

중요한 것은 하나를 골라 쓰는 게 아니라, 레이어를 나눠 함께 쓰는 것이다. 변하지 않는 정책은 Rules나 AGENTS.md에 두고, 자주 호출하는 절차는 Workflow로 만들고, 전문 영역은 Skill로 캡슐화하고, 그 사이사이에서 생기는 반복 판단을 Knowledge Base에 쌓는 식이다. 이렇게 해야 메모가 규칙을 침범하지 않고, 규칙이 대화의 유연성을 죽이지도 않는다.

좋은 Knowledge Item은 규칙이 아니라 판단을 담는다

초보 팀은 Knowledge Base를 만들 때 문장을 너무 짧게 쓴다.

"날짜 라이브러리는 date-fns 사용."

이 문장 자체는 틀리지 않다. 하지만 충분하지도 않다. 왜냐하면 에이전트가 실제 상황에서 만나게 되는 질문은 늘 더 복잡하기 때문이다. 기존 코드가 다른 라이브러리를 쓰고 있으면? 시간대 계산이 필요한 경우는? 새 의존성을 피하고 싶을 때는? 이미 유틸 래퍼가 있을 때는?

그래서 좋은 Knowledge Item은 규칙만 적지 않고, 결정과 이유와 예외의 방향을 함께 담는다.

예를 들어 이렇게 바뀌면 훨씬 강해진다.

날짜 처리는 기본적으로 공용 date 유틸을 우선 사용한다.
새로운 화면에서 직접 라이브러리를 추가하지 말고, 기존 유틸이 부족할 때만 확장한다.
시간대 계산이 필요한 경우에는 서버 기준 UTC 저장 규칙을 유지한다.

이 문장이 좋은 이유는 세 가지다. 무엇을 우선할지 알려 주고, 왜 그렇게 하는지 암시하고, 예외가 생겼을 때 어디를 먼저 보아야 하는지도 알려 준다.

Knowledge Base는 정답 모음집이 아니라 판단 비용 절감 장치다. 그러니 짧기만 한 문장보다, 실제 선택을 덜 헤매게 해 주는 문장이 훨씬 낫다.

팀 전체에 공유되는 지식 기반은 어떻게 만드는가

팀이 커질수록 Knowledge Base는 개인 메모장이 아니라 운영 체계가 된다. 이때 핵심은 "누가 잘 쓰느냐"가 아니라 "어떻게 누적되느냐"다.

반복된 코멘트를 승격하라

가장 쉬운 출발점은 반복이다. 같은 피드백을 세 번 이상 했다면, 그것은 더 이상 리뷰 코멘트가 아니라 팀 규칙 후보다.

예를 들어 이런 상황이 자주 생긴다. 에이전트가 API 오류 메시지를 페이지마다 다르게 만들고, 리뷰어가 매번 "실패 응답은 공통 에러 포맷을 유지해 달라"고 적는다. 이 피드백이 두세 번 반복됐다면, 이제부터는 대화에서만 말하지 말고 Knowledge Base로 올려야 한다.

좋은 운영자는 에이전트의 실수만 보지 않는다. 반복되는 수정 패턴을 본다. 그리고 그 패턴을 메모리로 승격한다.

선호보다 기준을 남겨라

"우리는 Zustand를 안 좋아해요"보다 "전역 상태는 여러 화면에서 동시 참조되는 경우에만 허용하고, 그 외에는 로컬 상태나 서버 상태 관리 도구를 우선한다"가 훨씬 낫다.

왜냐하면 팀은 취향보다 기준으로 움직여야 하기 때문이다. 선호만 남기면 사람마다 다르게 해석한다. 기준을 남기면 새 기능이 와도 같은 축으로 판단할 수 있다.

범위를 나눠라

지식 기반이 망가지는 가장 빠른 길은 개인 취향과 팀 정책과 프로젝트 특수사항을 한 통에 섞는 것이다.

가령 다크 테마를 좋아하는 것은 개인 취향일 수 있다. 하지만 "이 저장소는 모든 사용자 텍스트를 i18n 키로 관리한다"는 것은 프로젝트 규칙이다. 또 "핀테크 서비스이므로 금액 계산은 부동소수점 연산을 직접 쓰지 않는다"는 것은 도메인 제약이다.

이 셋은 강도가 다르다. 그러니 저장 위치와 적용 범위도 달라야 한다. 개인 스타일은 개인 범위에서, 저장소 규칙은 프로젝트 범위에서, 도메인 제약은 팀 공용 범위에서 관리해야 서로 덜 충돌한다.

중요한 것은 반드시 저장소에도 남겨라

Antigravity 안의 메모리가 편리하다고 해서, 중요한 규칙까지 거기에만 두면 안 된다. 정말 중요한 아키텍처 결정과 보안 규칙은 AGENTS.md, ADR, README, 설계 문서 같은 저장소 내부 파일에도 같이 남겨야 한다.

이유는 단순하다. 메모리는 편리하지만, 저장소 문서는 더 오래 산다. 툴이 바뀌어도 남고, 사람 리뷰어도 읽을 수 있고, CI나 다른 에이전트 도구와 연결하기도 쉽다. 사라지면 곤란한 지식일수록 툴 내부가 아니라 저장소에도 적어 두어야 한다.

시간이 갈수록 더 똑똑해지는 운영 루틴

Knowledge Base는 한 번 세팅하고 끝나는 기능이 아니다. 살아 있는 팀 운영과 함께 돌아가야 한다. 생각보다 거창한 의식은 필요 없다. 아래 정도 루틴만 있어도 체감 차이가 크다.

• 스프린트나 주간 단위로 반복된 리뷰 코멘트를 모아 신규 Knowledge Item 후보를 정한다.

• 새 규칙을 추가할 때는 한 줄 금지문보다 적용 기준과 예외 방향까지 같이 적는다.

• 프로젝트의 핵심 원칙은 AGENTS.md나 저장소 문서에도 함께 반영해 단일 툴 의존을 줄인다.

• 오래된 항목은 분기마다 정리해 지금도 유효한지 확인한다.

이 루틴이 중요한 이유는 메모리도 부패하기 때문이다. 예전에는 맞았던 규칙이 지금은 틀릴 수 있다. 한때 금지했던 라이브러리가 지금은 표준이 되었을 수도 있다. 테스트 전략이 바뀌었는데 옛 지침이 그대로 남아 있으면, 에이전트는 성실하게 구식 결정을 반복한다.

좋은 팀의 Knowledge Base는 점점 두꺼워지는 문서가 아니다. 점점 더 정제되는 운영 체계다.

실전 예시: 이런 문장이 팀을 닮게 만든다

추상적인 이야기만 하면 손에 안 잡힌다. 실제로는 아래와 같은 문장들이 꽤 강력하다.

첫째, 코드 구조에 대한 문장이다.

비즈니스 로직은 route handler에 직접 두지 않는다.
handler는 입력 검증과 응답 변환만 맡고, 실제 처리 로직은 service 계층으로 보낸다.
새 기능을 추가할 때도 같은 분리를 유지한다.

이 메모는 단순해 보이지만, 아키텍처 일관성에 미치는 영향이 크다. 에이전트가 기능을 빨리 완성하려고 가장 쉬운 자리에 로직을 욱여넣는 습관을 막아 준다.

둘째, UI 작업에 대한 문장이다.

사용자 인터랙션이 바뀌는 UI 수정은 가능하면 스크린샷 또는 브라우저 검증 흔적을 남긴다.
시각적 배치만 바뀌는 변경도 모바일 뷰포트에서 한 번 더 확인한다.

이 메모는 기술 선택이 아니라 검증 습관을 강제한다. 결과적으로 "고쳤다는데 직접 켜 보면 다르다"는 상황이 줄어든다.

셋째, 라이브러리 선호에 대한 문장이다.

새로운 유틸 라이브러리를 바로 추가하지 말고, 먼저 현재 코드베이스의 공용 유틸과 표준 함수로 해결 가능한지 확인한다.
의존성 추가가 필요하면 이유를 변경 요약에 남긴다.

이 메모는 번들 크기, 일관성, 장기 유지보수 비용을 동시에 관리한다. 그리고 무엇보다 좋다. 사람도 같은 기준으로 리뷰하게 된다.

Knowledge Base의 진짜 힘은 여기에 있다. 에이전트만 통제하는 게 아니라, 팀의 리뷰 언어까지 정렬한다.

안티패턴: 많이 쌓는다고 좋은 게 아니다

지식 기반을 운영하다 보면 흔히 빠지는 함정들이 있다.

첫 번째는 모든 것을 넣는 것이다. 회의 메모, 배경 설명, 기획 아이디어, 한 번 쓰고 말 명령까지 다 넣으면 결국 아무도 안 읽는다. 지식 기반은 기억 창고가 아니라 행동 엔진이다.

두 번째는 취향을 정책처럼 쓰는 것이다. 어떤 개발자의 선호를 팀의 비가역 규칙으로 적어 버리면 반발만 커진다. "왜"가 없는 지식은 오래 못 간다.

세 번째는 예시가 없는 것이다. "가독성 좋게 작성" 같은 말은 사람끼리도 모호하다. 반면 "비동기 오류 처리는 toast + fallback UI 패턴을 따른다"처럼 예시가 있으면 훨씬 강해진다.

네 번째는 소유자가 없는 것이다. 누가 업데이트할지 정해지지 않으면 문서는 늙고, 늙은 문서는 결국 방해물이 된다.

다섯 번째는 툴 내부 메모만 믿는 것이다. 특히 프리뷰 제품을 다룰 때는 더 조심해야 한다. 실제 커뮤니티 포럼에서도 Knowledge Base가 비어 보이거나 항목이 사라지는 현상, 항목 수 제한 같은 운영 이슈가 보고된 바 있다.⁵ 그래서 중요한 정책은 반드시 저장소 문서에도 함께 남겨 두는 편이 안전하다.

추가와 편집은 어떻게 해야 하는가

이 장의 제목이 Knowledge Base라고 해서, 마치 별도의 거대한 시스템부터 만들어야 할 것처럼 느낄 필요는 없다. 오히려 반대다. 시작은 아주 작게 하는 편이 좋다.

먼저 최근 2주 동안 에이전트에게 반복해서 말한 문장을 떠올려 보자. 그중 세 번 이상 나온 것이 있다면 후보 1순위다.

그다음 그 문장을 다음 순서로 다듬는다. "무엇을 하라"만 쓰지 말고, "언제 이 규칙이 적용되는지", "왜 이런 선택을 하는지", "예외가 생기면 어디를 볼지"를 짧게 붙인다.

그 뒤 범위를 정한다. 개인 취향인지, 이 저장소만의 규칙인지, 팀 전체 규칙인지 구분한다. 그리고 저장 위치를 정한다. 변하지 않는 핵심은 저장소 문서로, 자주 진화하는 실행 지식은 Knowledge Base로, 항상 강제해야 하는 정책은 Rules로 보내면 된다.

마지막으로 중요한 것은 연결이다. 새 작업을 위임할 때 그냥 "알아서 해"라고 하지 말고, 관련된 지식을 함께 참조하게 해야 한다. 그래야 Knowledge Base가 박제된 문서가 아니라 실제 행동을 바꾸는 시스템이 된다.

결국 Knowledge Base는 팀의 두 번째 시니어다

주니어 개발자가 팀에 들어오면 처음 몇 주 동안 같은 질문을 반복한다. 파일 구조는 왜 이런지, 왜 이 라이브러리를 안 쓰는지, 테스트는 어디까지 쓰는지, 어떤 변경은 왜 꼭 스크린샷을 남겨야 하는지 묻는다. 시간이 지나면 그 사람은 점점 팀답게 일하기 시작한다.

Knowledge Base가 하는 일이 바로 그것이다. 에이전트를 팀의 두 번째 시니어로 만드는 것이 아니라, 적어도 매번 새로 온 인턴으로 되돌아가지 않게 만든다.

작업을 잘게 쪼개는 능력이 "이번 일을 실패하지 않게 만드는 기술"이었다면, Knowledge Base는 "다음 일부터 같은 실수를 덜 하게 만드는 기술"이다. 전자는 실행의 품질을 높이고, 후자는 반복의 품질을 높인다. 둘이 만나야 진짜 팀 생산성이 올라간다.

반복되는 설명을 자산으로 바꾸는 순간, 에이전트는 점점 더 팀답게 일한다. 그리고 그때부터 개발자는 더 이상 같은 말을 백 번 반복하는 사람이 아니라, 지식을 설계하고 누적하는 관리자가 된다.

이 장의 핵심

Knowledge Base의 본질은 메모 보관이 아니라 반복 설명의 자산화다. 한 번의 좋은 지시보다, 다음에도 재사용되는 좋은 기준이 훨씬 큰 생산성 차이를 만든다.

지식 기반에는 코드 컨벤션, 기술 선호, 아키텍처 결정, 검증 습관처럼 에이전트가 추측하기 어려운 팀의 판단 기준을 넣어야 한다. 특히 규칙만이 아니라 결정 이유와 적용 맥락을 함께 남겨야 실제 선택이 달라진다.

Rules, Workflows, Skills, AGENTS.md, Knowledge Base는 서로 경쟁하는 기능이 아니다. 항상 지켜야 할 것, 필요할 때 호출할 것, 전문 지식 묶음, 저장소 운영 지침, 지속 기억이라는 서로 다른 레이어로 이해해야 한다.

무엇보다 중요한 것은 운영 루틴이다. 반복된 코멘트를 승격하고, 핵심 지식은 저장소에도 남기고, 오래된 규칙은 정리해야 한다. 그래야 에이전트가 시간이 갈수록 정말로 더 팀답게 일한다.

참고

¹Google Antigravity Knowledge 문서

²일관성 있는 Agentic AI Workflow를 팀 프로젝트에 적용하는 법

³Google Antigravity 실전 개발자 가이드

⁴Complete Guide to Google Antigravity

⁵Knowledge: how to make it works? - Google AI Developers Forum