안녕하세요. 클라우드 에이스(Cloud Ace) 주식회사 제1개발부의 키무라입니다.

일상적인 개발이나 운용에서 AIDD (AI 주도 개발)를 의식하며 업무를 진행하는 가운데, 지식 공유 메커니즘에 대해 고민해 보았습니다.

서론

Claude Code나 Cursor와 같은 AI 코딩 에이전트는 일상적인 개발이나 인프라 운용에서 이제 없어서는 안 될 존재가 되었습니다. 반면, 지속적인 클라이언트 워크에서 AI 에이전트를 깊이 있게 사용하다 보면 어떤 공통적인 벽에 부딪히게 됩니다.

"이 에이전트, 매번 처음부터 이야기를 듣고 있는 것 같다"

티켓 대응에서 얻은 지식도, 장애 조사에서 얻은 요령도, 세션이 끝나면 그 에이전트 안에는 남지 않습니다. 다음에 비슷한 대응을 할 때는 다시 처음부터 상황을 설명하고, 다시 처음부터 조사해야 합니다. 이는 인간 팀으로 치면, 우수한 담당자가 매번 기억상실증 상태로 출근하는 것과 같습니다.

이 기사에서는 어느 클라이언트의 지속적인 프로젝트에서 AI 에이전트 운용 기반을 만들면서 보게 된, "AI 에이전트를 팀의 자산으로 키우기" 위한 3가지 설계 패턴을 소개합니다. 특정 도구나 클라이언트에 의존하지 않고, 리포지토리(Repository) 구조만으로 실현할 수 있는 이야기입니다.

생각의 베이스에는 저희 회사의 공식 note인 'AI 주도 개발의 전체상 #6 탐색과 수렴을 「같은 메커니즘」으로 돌리기'가 있습니다. 해당 기사에서 언급된 "정해진 규칙을 파일로 관리하고, 탐색을 통해 얻은 지식을 쌓아 나간다"라는 발상을, 지속적인 프로젝트에서의 AI 에이전트 운용 현장에 적용하여 생각하고 있습니다.

참고로, 여기서 소개하는 메커니즘은 이제 막 운용을 시작한 '시안(たたき台)' 단계이며, 완성형이 아니라 개선의 여지가 많은 상태라는 전제하에 읽어 주시기 바랍니다. 그럼에도 가설로서 공유할 가치가 있다고 판단하여 현시점의 형태를 정리했습니다.

발상의 전환: AI 에이전트를 「성장하는 신입」으로 취급하기

인간 신입 사원이 입사했을 때, 우리는 무엇을 할까요? 역할별 온보딩 자료를 전달하고, 과거 대응 사례를 공유하며, 모르는 것은 선배에게 물어볼 수 있는 상태를 만듭니다. 그리고 신입 스스로도 대응한 안건을 메모로 남기며, 점차 자신의 판단으로 움직일 수 있게 됩니다.

AI 에이전트에 대해서도 동일한 것을 리포지토리 구조로서 해주면 된다——이것이 출발점이 된 발상입니다. 에이전트의 「기억」을 세션이나 모델 내부에서 기대하는 것이 아니라, Git 리포지토리라는 외부 기억 장치에 갖게 하는 것입니다.

구체적으로는 다음의 3가지 설계 패턴으로 구체화했습니다.

패턴 1: 역할별 작업 디렉토리

먼저, 에이전트가 담당하는 역할(유스케이스)별로 디렉토리를 나누고, 각각에 「역할 정의」, 「절차서」, 「작업용 3분할 폴더」를 갖게 합니다.

agents/
└── <유스케이스명>/
├── AGENT.md # 이 에이전트의 역할·사용법
...

포인트는 inbox

→ work

→ outbox

라는 일방향 흐름과, work/ 만은 의도적으로 버전 관리(Version Control)에서 제외하는 것입니다. 작업 중인 파일은 개인적·일시적인 것이 되기 쉬우며, 여러 사람이 AI 에이전트를 병행해서 사용하는 팀에서는 이곳을 버전 관리 하에 두면 컨플릭트(Conflict)의 온상이 됩니다. 반대로 inbox (입력)와 outbox (성과물)는 팀에서 공유할 가치가 있기 때문에, 평소와 같이 Git 관리 하에 둡니다.

"무엇이든 Git으로 관리한다"가 아니라, 충돌하기 쉬운 것은 의도적으로 관리 외로 두는 선긋기가, 미미하지만 팀 운용에서는 효과적입니다.

패턴 2: 단일 지식원과, 도구를 교체해도 잃어버리지 않는 어댑터 설계

두 번째는 지식을 한 곳에 집약하는 패턴입니다.

knowledge/
├── domain/ # 용어집 등, 모든 유스케이스를 관통하는 지식
├── constraints/ # 계정·권한·체제 등의 제약 사항
...

여기서 중요한 것은 AI 도구별 설정 파일(Cursor의 규칙 파일, Claude Code의 CLAUDE.md 등)에 지식 그 자체를 쓰지 않는 것입니다. 도구의 설정 파일은 어디까지나 "이곳을 확인해 주세요"라고 가리키는 얇은 어댑터(Adapter) 역할에 충실하게 하고, 지식의 본체는 knowledge/로 일원화합니다.

[도구 A용 규칙 파일] ─┐
├─→ knowledge/ （유일한 지식원）
[도구 B용 규칙 파일] ─┘

이렇게 해두면 팀이 사용하는 AI 도구가 바뀌더라도 (Cursor에서 Claude Code로, 혹은 그 반대로), 어댑터(Adapter)를 하나 교체하는 것만으로 충분하며 축적된 지식(Knowledge) 자체는 손실되지 않습니다. 도구 간의 주도권 싸움으로부터 지식을 분리해 두는 것입니다.

이해를 돕기 위해, 여러 프로젝트에서 발견된 요소들을 합성한 가상의 예시를 소개합니다 (실제 프로젝트, 기업, 시스템과는 무관합니다).

# CLAUDE.md
이 파일은 Claude Code가 이 리포지토리(Repository)에서 작업할 때 가이던스를 제공합니다.
## 이 리포지토리에 대하여
...

포인트는 CLAUDE.md 자체에는 "어디에 어떤 규칙이 적혀 있는가"라는 목차 이상의 정보를 담지 않고, 실제 도메인 지식(Domain Knowledge)이나 배포 절차의 상세 내용은 knowledge/나 agents/<domain>/ 측에 두는 것입니다. 이러한 가벼움이 도구를 교체할 때의 민첩성으로 직결됩니다.

패턴 3: 기록 전담 에이전트에 의한 2단계 지식 축적

세 번째는 개인적으로 가장 효과가 크다고 느끼는 패턴입니다.

지견(Insight)을 자산화하는 데 있어 최대의 적은 "번거로움"입니다. 대응이 끝난 후에 "이 케이스를 지식화할 가치가 있는가"를 매번 판단하게 하려 하면, 판단 비용이 높아 아무도 하지 않게 됩니다.

그래서 기록을 **"기계적으로 기록하기만 하는 역할"**과 **"가끔 선택하여 승화시키는 역할"**의 2단계로 나누었습니다.

• 기록 담당 에이전트 (Recording Agent): 판단은 일절 하지 않고, 대응이 일단락될 때마다 knowledge/work-log/에 건당 하나씩 기계적으로 로그를 추가하기만 하는 전담 에이전트. "무엇을 했다·무엇이 일어났다·막혔던 점"을 3줄 정도로 작성할 뿐이므로, 사고 비용(Thinking Cost)이 거의 들지 않습니다.
• 지식화 프롬프트 (Knowledge-ification Prompt): work-log가 쌓여서 동일한 패턴이 여러 번 나타날 때 비로소, 사람이 취사선택하며 playbooks/나 knowledge/로 승화시킵니다.

대응 완료
→ 기록 담당이 work-log에 1건 기록 (기계적·판단 불필요·매번 수행)
→ 패턴이 보이기 시작하면
...

"일단 전부 기록한다"는 허들을 극한까지 낮추면서, "가치 있는 것만을 정리된 지식으로 만든다"는 판단은 별도의 타이밍으로 분리합니다. 이 이중 구조를 통해, 지식화할 정도는 아닌 개별 케이스도 나중에 검색 가능한 자산으로서 남길 수 있게 됩니다.

가드레일: 자율과 승인의 균형

지금까지의 메커니즘은 에이전트에게 "자율적으로 움직여도 좋은 범위"를 넓히기 위한 토대이기도 합니다. 그렇기에 가드레일(Guardrail)도 세트로 정해둘 필요가 있습니다.

• 읽기·조사는 자율 실행 가능: 검색·열람·과거 로그 참조는 매번 확인을 거치지 않고 에이전트에게 맡깁니다.
• 쓰기는 승인제: 파일 변경·전송·생성·삭제 등 모든 변경 작업은 내용을 초안(Draft)으로 제시한 후 승인을 얻어 실행합니다.
• 운영 환경에 영향을 주는 작업은 반드시 사전 리뷰: 권한 변경이나 인프라의 운영 환경 적용 등 되돌리기 어려운 작업은 일반적인 승인보다 한 단계 더 두터운 리뷰를 거칩니다.

"지식을 축적하여 똑똑해진 에이전트에게 어디까지 재량권을 줄 것인가"는 축적 메커니즘과 세트로 설계해 두지 않으면, 똑똑해질수록 무서워지는 구조가 되어버립니다.

이 형태가 "정답"인지는 솔직히 아직 모릅니다

지금까지 3가지 패턴을 정리해 왔지만, 이것이 최적해(Optimal Solution)라고 단언할 자신은 없습니다.

• inbox/work/outbox의 3분할이 정말 이 입도(Granularity)로 적절한지, 더 적어도 돌아가지 않을지
• knowledge/domain과 constraints의 분리가 지식이 늘어났을 때 파탄 나지 않을지
• 기록 담당 에이전트에 의한 2단계 운용도 팀 규모가 커졌을 때 동일하게 기능할지

이러한 질문들에 대해서는 아직 스스로 답을 내지 못했습니다. 현재로서는 소규모 팀에서 잘 돌아가고 있을 뿐, 다른 클라이언트나 다른 규모에서 동일한 구조를 도입했을 때 똑같이 기능할지는 미검증 상태입니다.

"현시점에서 시도하고 있는 가설 중 하나" 정도의 온도감으로 읽어주신다면 실태에 가까울 것입니다.

그럼에도 불구하고, 실제로 작동시켜 보면서 검증해 볼 가치는 있다고 생각합니다. 처음부터 완성된 형태를 목표로 하기보다, 잘 풀리지 않는 부분은 그때마다 다시 검토하면 됩니다. 오히려 시도해 보지 않고서는 "어디에서 파탄이 날지"조차 알 수 없다는 것이 실감됩니다. 실패를 포함해서, 우선 작게 시도해 보는 것이 책상 위에서 정답을 계속 찾는 것보다 더 빠르게 앞으로 나아갈 수 있는 방법입니다.

마치며: 작게 시작하여, 사용하며 키워나가기

이 세 가지 패턴의 공통점은 특별한 도구나 플랫폼을 필요로 하지 않는다는 것입니다. 필요한 것은 Git 리포지토리(Repository)와 폴더를 분리하는 규율, 그리고 "기계적인 기록"과 "인간의 취사선택"을 구분한다는 운영 규칙뿐입니다.

소개한 메커니즘 자체도 처음부터 완벽한 형태로 도입한 것은 아닙니다. 지금도 여전히 "소규모 팀이니까"라며 넘어가고 있는 간이 운영 방식이 있고, 정리되지 않은 메모도 남아 있습니다. 그럼에도 "에이전트가 기억을 잃지 않는 메커니즘"을 먼저 만들어 둠으로써, 사용하면 할수록 팀과 에이전트 모두가 똑똑해지는 상태에는 가까워졌다고 느끼고 있습니다.

만약 여러분의 프로젝트에서도 "AI 에이전트에게 물어본 것을, 에이전트가 다시 똑같은 것을 되묻는" 상황이 짐작된다면, 우선 work/ 디렉토리를 분리하여 Git 관리 대상에서 제외하는 것부터라도 시도해 보신다면 좋겠습니다.

Discussion