GitAgent 사용법 정리 2026 — agent.yaml과 SOUL.md로 AI 에이전트를 Git으로 관리하면 뭐가 달라지나

2026년 3월 26일 기준 GitAgent 공식 README와 공식 사이트는 GitAgent를 Git-native, framework-agnostic AI agent standard로 설명한다.

핵심은 두 파일이다.

agent.yaml은 설정과 역할을 담고, SOUL.md는 정체성과 말투를 담는다.

그리고 나머지는 전부 Git으로 다룬다.

2025년까지 AI 에이전트 운영 얘기를 하면 보통 런타임부터 떠올렸다.

어느 SDK를 쓰는지, 어느 벤더 콘솔에 올리는지, 어느 대시보드에서 프롬프트를 바꾸는지가 중심이었다.

그런데 2026년부터 진짜 불편한 건 따로 보이기 시작했다.

에이전트가 어디에 정의돼 있는지 너무 제각각이라는 점이다.

한쪽은 시스템 프롬프트가 대시보드에 있고, 한쪽은 YAML 한 장이고, 다른 한쪽은 코드 안에 하드코딩돼 있다.

그러면 뭐가 힘드냐.

리뷰가 힘들다.

버전 관리가 힘들다.

팀 협업이 힘들다.

그리고 벤더를 옮길 때마다 인간이 먼저 지친다.

GitAgent는 바로 그 불편을 겨냥한 도구다.

질문은 여기서 시작된다.

진짜로 이걸 쓰면 에이전트 운영이 쉬워질까.

아니면 또 하나의 예쁜 표준 문서가 늘어나는 걸까.

우리처럼 .claude/agents, .claude/skills, .claude/rules, .claude/MEMORY를 이미 굴리고 있는 팀에도 의미가 있을까.

실사용 기준으로 보면 답은 생각보다 단순하다.

정체성, 구조, 협업, 이식성에는 도움이 된다.

하지만 런타임, 상태 복구, 실제 툴 실행, 긴 작업 하네스까지 한 번에 해결해주진 않는다.

즉, GitAgent는 엔진이라기보다 규격에 가깝다.

이 차이를 모르고 들어가면 실망한다.

이 차이를 알고 쓰면 꽤 쓸만하다.

이 글에서는 GitAgent 공식 README와 공식 사이트를 기준으로, agent.yaml과 SOUL.md가 실제 워크플로에서 어디까지 먹히는지, 우리 .claude 구조와 비교하면 뭐가 맞고 뭐가 비는지, 협업과 버전 관리에는 왜 꽤 매력적인지, 그리고 아직 뭐가 부족한지까지 정리해보겠다.

참고로 이번 정리는 GitAgent 공식 문서 리딩과 우리 워크스페이스 구조 매핑을 바탕으로 썼다.

즉, “프로덕션 전체를 GitAgent로 옮겨본 후기”는 아니다.

대신 “지금 이걸 파일럿으로 붙이면 어디까지 이득이고 어디서부터 추가 공사가 필요한가”를 판단하는 글에 가깝다.

이 글이 필요한 사람

Claude Code, OpenAI, CrewAI처럼 에이전트 정의가 여러 런타임에 흩어져 있어서 정리가 필요한 팀
.claude, prompts/, scripts/, 대시보드 설정이 따로 놀아서 누가 뭘 바꿨는지 추적이 답답한 사람
에이전트도 코드처럼 branch, PR, diff로 관리하고 싶은 운영팀
반대로 “이거 또 표준병 걸린 거 아냐?” 하고 의심하는 사람

이 중 하나라도 걸리면 GitAgent를 한 번쯤 볼 이유는 있다.

지금 결론

GitAgent는 “에이전트를 Git 저장소의 파일로 정의하자”는 제안이다.

이 아이디어 자체는 꽤 좋다.

왜냐면 에이전트도 결국 팀이 관리해야 하는 운영 자산이기 때문이다.

코드처럼 리뷰하고, 브랜치로 실험하고, 태그로 릴리스하고, PR로 감사 흔적을 남길 수 있다.

이건 생각보다 크다.

특히 여러 워커가 동시에 움직이는 환경에서는 더 그렇다.

누가 어떤 역할 정의를 바꿨는지, 어떤 규칙이 추가됐는지, 어떤 스킬이 빠졌는지 diff로 보는 게 가능해진다.

공식 README도 이 지점을 강하게 민다.

Git-native라는 말이 그냥 장식 문구가 아니다.

브랜치, diff, versioning, audit, PR 기반 협업이 제품 개념의 가운데에 있다.

최소 구조도 단순하다.

필수 파일은 agent.yaml과 SOUL.md 두 개뿐이다.

README가 이 점을 명확히 적어둔다.

agent.yaml은 manifest다.

이름, 버전, 모델, 스킬, 툴, 규정 준수 같은 걸 담는다.

SOUL.md는 identity다.

성격, 말투, 가치관, 커뮤니케이션 스타일을 담는다.

여기까지는 진짜 깔끔하다.

문제는 여기서 끝나지 않는다는 거다.

실제 운영은 늘 더 지저분하다.

어떤 런타임을 탈지, 어떤 툴을 실제로 호출할지, 메모리를 어디에 쓸지, 반복 루프를 누가 돌릴지, 실패 시 복구는 어떻게 할지 같은 건 그대로 남는다.

README도 이걸 숨기지 않는다.

무엇이 프레임워크에 남는지 따로 적어둔다.

runtime orchestration, live tool execution, memory I/O, iterative loops는 여전히 런타임 몫이라고 말한다.

그래서 내 판단은 이렇다.

GitAgent는 “에이전트 정의 레이어”를 정리하는 데는 꽤 유용하다.

하지만 “실행 레이어”를 대체하지는 못한다.

우리처럼 이미 .claude 아래에 에이전트 정의, 스킬, 메모리, 규칙, 스크립트, 하네스가 나뉘어 있는 팀이라면 더 명확하다.

GitAgent는 위쪽 레이어를 단정하게 묶는 데 좋다.

하지만 하네스까지 대신 돌려주진 않는다.

그래서 언제 좋으냐.

벤더나 런타임을 자주 바꾸는 팀.

에이전트 정의를 Git으로 리뷰하고 싶은 팀.

역할 분리와 감사를 중요하게 보는 팀.

공용 모노레포에서 여러 에이전트를 같이 키우는 팀.

언제 아직 별로냐.

혼자 빠르게 실험만 하는 사람.

지금 당장 필요한 게 표준화보다 실행 안정성인 팀.

에이전트 정의보다 툴 호출 자동화와 복구 루프가 더 급한 팀.

즉, GitAgent는 “운영 문명화”에는 도움 된다.

그렇다고 자동으로 생산성이 폭발하진 않는다.

그 기대치를 낮추고 들어가면 꽤 괜찮다.

GitAgent가 실제로 바꾸는 것

GitAgent를 한 줄로 보면 “에이전트도 저장소 안에서 다루자”다.

근데 실무에선 이 한 줄이 은근히 큰 차이를 만든다.

첫째, 정의 위치가 고정된다.

에이전트 정체성이 슬랙 핀 메시지에 있고, 시스템 프롬프트는 어떤 노션 문서에 있고, 툴 스키마는 다른 폴더에 있고, 운영 규칙은 팀장 머릿속에 있는 상태가 제일 피곤하다.

GitAgent는 그걸 repo로 끌어온다.

공식 README 예시 구조를 보면 agent.yaml, SOUL.md, skills/, tools/, memory/, hooks/, workflows/, knowledge/, config/, compliance/, agents/ 같은 폴더가 등장한다.

여기서 중요한 건 “전부 다 써야 한다”가 아니다.

오히려 반대다.

필수는 둘이고 나머지는 선택이다.

이게 첫 장점이다.

처음부터 무거운 프레임워크를 강제하지 않는다.

둘째, 리뷰 단위가 명확해진다.

예를 들어 SOUL.md에서 에이전트의 말투를 바꾸거나, agent.yaml에서 사용할 스킬과 권한을 조정하면 그 변경이 diff로 남는다.

누가 어떤 정체성을 어떻게 바꿨는지 PR에서 토론할 수 있다.

이건 사람 팀원 온보딩에도 좋다.

“왜 이 에이전트가 이렇게 답하죠?”라는 질문에 문서 경로를 바로 던질 수 있다.

셋째, 이식성 얘기를 좀 더 현실적으로 할 수 있다.

공식 사이트 FAQ는 GitAgent를 framework-agnostic이라고 설명한다.

Claude, OpenAI, CrewAI, Lyzr 같은 여러 생태계로 내보낼 수 있다고 말한다.

여기서 중요한 건 “정의”를 옮기기 쉬워진다는 점이다.

사람들이 자주 착각하는 건 실행 전체가 자동으로 이식된다고 믿는 거다.

그건 아니다.

정체성과 설정, 스킬 구조는 옮기기 쉬워진다.

하지만 툴 체인 연결 방식, 실제 런타임 어댑터, 상태 전이 로직은 여전히 손이 간다.

넷째, 협업 모델이 Git과 닮아진다.

README는 human-in-the-loop 패턴으로 branch + PR 리뷰를 말한다.

에이전트가 새 스킬을 배우거나 메모리를 쓸 때도 사람 리뷰를 끼울 수 있다는 얘기다.

이건 통제가 필요한 팀에는 꽤 매력적이다.

특히 금융, 법무, 보안처럼 “그냥 알아서 하게 두면 곤란한” 영역에서는 더 그렇다.

다섯째, 에이전트 버전 관리를 소프트웨어 버전 관리처럼 가져갈 수 있다.

README에는 tagged release, branch-based deployment, audit trail 같은 표현이 반복된다.

이 말은 staging 에이전트와 production 에이전트를 따로 굴리는 발상이 가능하다는 뜻이다.

에이전트도 dev -> staging -> main으로 올릴 수 있다는 얘기다.

이건 생각보다 실용적이다.

프롬프트 한 줄 바꿔서 production에서 사고 치는 걸 줄일 수 있으니까.

여섯째, 역할 분리 이야기를 자연스럽게 꺼낼 수 있다.

README는 maker, checker, executor, auditor 같은 역할 분리를 예로 든다.

한 에이전트가 모든 걸 다 하게 두지 말라는 얘기다.

실제 운영에선 이게 중요하다.

콘텐츠 파이프라인이든 코드 리뷰든 “만드는 놈”과 “검사하는 놈”을 분리해야 사고가 줄어든다.

우리가 여러 워커를 병렬로 쓰는 이유랑도 닿아 있다.

그렇다고 무조건 다 좋아지는 건 아니다.

이 구조를 받아들이면 리뷰 부담도 생긴다.

에이전트 설정을 바꾸는 모든 일이 PR 이벤트가 되면 운영 속도가 늦어질 수 있다.

문서 품질 유지 비용도 생긴다.

SOUL.md를 잘 써야 하고, agent.yaml을 꾸준히 맞춰야 하고, 스킬과 툴 메타도 관리해야 한다.

즉, SaaS 구독료 대신 리뷰 비용과 운영 비용이 늘어나는 느낌이다.

그래서 GitAgent는 “공짜로 좋아지는 해법”이 아니다.

대신 “복잡도를 눈에 보이게 바꾸는 해법”에는 가깝다.

이건 꽤 가치 있다.

복잡도가 안 보일 때가 제일 위험하니까.

agent.yaml과 SOUL.md만으로 어디까지 되나

GitAgent를 처음 보면 제일 궁금한 게 이거다.

진짜 파일 두 개만 있으면 뭐가 되는데?

공식 README 답은 분명하다.

필수는 agent.yaml과 SOUL.md 두 개다.

그리고 공식 사이트 FAQ는 설치 흐름도 비교적 단순하게 적어둔다.

npm install -g gitagent

gitagent init --template standard

gitagent validate

필요하면 gitagent run이나 gitagent export로 이어간다.

여기서 agent.yaml은 manifest 역할을 한다.

이름, 버전, 모델, 스킬, 툴, 권한, 규정 준수 정책, 역할 분리 같은 걸 구조화해서 담는다.

즉, 사람이 읽는 설명문보다는 운영 메타데이터에 가깝다.

반면 SOUL.md는 사람이 읽는 말에 가깝다.

이 에이전트가 누구처럼 말하는지, 무엇을 중시하는지, 어떤 태도로 사용자와 상호작용하는지를 서술한다.

이 구분은 꽤 좋다.

왜냐면 설정과 정체성은 자주 섞여서 망가지기 때문이다.

프롬프트 한 파일 안에 역할, 말투, 금지 규칙, 도구 허용 범위, 배포 정책, 팀 규칙이 다 섞이면 나중에 관리가 지옥이 된다.

GitAgent는 이걸 쪼갠다.

그게 장점이다.

그리고 여기서 끝내도 어느 정도는 된다.

최소한 에이전트의 정체성과 운영 설정을 Git 안으로 데려올 수 있다.

문서 리뷰가 가능해지고, export 경로를 고민할 수 있고, 저장소 기준의 온보딩 문서로도 쓸 수 있다.

하지만 실제 운영으로 넘어가면 금방 다음 질문이 나온다.

스킬은 어디에 두지?

툴 정의는 어떻게 하지?

실행 전후 훅은?

메모리는?

팀 에이전트는?

여기서 README가 제안하는 선택 폴더들이 등장한다.

skills/는 재사용 가능한 능력 모듈이다.

tools/는 MCP 호환 툴 스키마다.

memory/는 세션 간 상태를 두는 공간이다.

hooks/는 부트스트랩과 teardown 같은 라이프사이클 제어다.

agents/는 하위 에이전트다.

workflows/는 좀 더 결정론적인 절차를 둘 때 쓰기 좋다.

즉, GitAgent는 “두 파일이면 시작 가능”하고, “폴더를 늘리면 팀 운영 구조까지 담을 수 있다”는 식이다.

이건 꽤 현실적인 확장 방식이다.

다만 여기서 한계도 바로 보인다.

파일 구조가 있다고 런타임이 생기진 않는다.

tools/에 YAML을 둔다고 실제 실행 루프가 자동으로 품질 좋아지는 건 아니다.

memory/ 폴더가 있다고 메모리 충돌이 저절로 해결되는 것도 아니다.

hooks/가 있다고 장기 작업 실패 복구가 공짜로 붙는 것도 아니다.

즉, GitAgent는 “정리된 정의”를 준다.

하지만 “안 깨지는 실행”은 따로 챙겨야 한다.

이걸 혼동하면 실망 포인트가 빨리 온다.

실제로 README도 프레임워크가 계속 맡는 영역을 따로 적어둔다.

runtime orchestration은 그대로다.

live tool execution도 그대로다.

memory I/O도 그대로다.

iterative loop도 그대로다.

이건 나쁜 얘기가 아니다.

오히려 정직한 얘기다.

GitAgent는 만능 런타임이 아니라 개방형 표준에 더 가깝다.

이걸 인정하고 쓰면 설계가 깔끔해진다.

이걸 무시하고 쓰면 “왜 안 다 해주지?”라는 불만만 커진다.

우리 `.claude` 구조와 GitAgent를 나란히 놓으면

우리 워크스페이스는 이미 꽤 강한 구조를 갖고 있다.

.claude/agents가 있고, 팀 단위 디렉터리가 있다.

.claude/skills가 있고, 작업 단위 스킬이 쌓여 있다.

.claude/rules와 .claude/docs가 있고, 운영 정책과 제작 가이드가 나뉘어 있다.

.claude/MEMORY도 있다.

여기에 scripts, config, prompts, commands, ontology, MCP 서버까지 붙어 있다.

솔직히 말하면 이건 이미 “아무 구조도 없는 에이전트 모음”이 아니다.

꽤 잘 자란 운영체제다.

그럼 GitAgent가 여기서 해줄 일이 없을까.

그건 또 아니다.

오히려 매핑해보면 꽤 잘 맞는 부분이 있다.

먼저 SOUL.md 관점부터 보자.

우리 쪽 에이전트 md 파일은 역할, 톤, 책임, 규칙, 입출력, 협업 방식을 많이 담고 있다.

이 중 성격과 태도, 커뮤니케이션 원칙, 협업 철학은 SOUL.md로 뽑아내기 좋다.

예를 들어 “친근하지만 정확하게”, “사용자를 불필요하게 일시키지 않기”, “병렬 워커 환경에서 소유 범위를 지키기” 같은 건 정체성 레이어다.

이건 SOUL.md로 분리하면 더 명확해진다.

반대로 실행 절차, 산출물 구조, 채널별 규칙, 포맷 요구사항은 SOUL.md보다 RULES.md나 workflows/ 쪽이 더 어울린다.

그다음 agent.yaml을 보자.

지금 우리 구조에서는 에이전트별 메타데이터가 md frontmatter, 팀 문서, 하네스 설정, 실행 관행에 흩어져 있다.

이걸 manifest로 끌어모으면 관리 포인트가 줄어든다.

모델, 허용 스킬, 툴 목록, 역할, 컴플라이언스, 의무 분리 같은 걸 한 군데서 볼 수 있기 때문이다.

특히 여러 런타임을 같이 쓸 때 이게 좋다.

Claude Code에서 쓰는 정의와 다른 도구에서 쓰는 정의가 자꾸 갈라지는 문제를 줄일 수 있다.

skills/ 매핑도 좋다.

우리 .claude/skills는 이미 GitAgent가 상정하는 reusable capability module과 닮아 있다.

각 스킬마다 SKILL.md가 있고, 일부는 스크립트와 참조 문서를 동반한다.

이건 GitAgent 철학과 잘 맞는다.

memory/도 마찬가지다.

우리 .claude/MEMORY는 hot, warm, cold, agents, teams로 나뉘어 있다.

GitAgent README가 말하는 memory/runtime/ 구조와 완전히 같진 않지만, “에이전트 상태를 Git으로 보거나 적어도 파일 시스템에서 명시적으로 관리한다”는 발상은 통한다.

tools/도 연결 고리가 있다.

우리는 MCP 서버와 툴 정의를 이미 운영하고 있다.

GitAgent의 tools/ 폴더는 이걸 좀 더 선언적으로 모아두는 창구가 될 수 있다.

문제는 여기서부터다.

우리 구조에는 GitAgent보다 더 큰 것이 있다.

하네스다.

장기 작업 감시, 자동 재시작, 상태 파일 복원, 일일 점검, 백필, 시트 동기화 같은 건 단순한 agent definition을 넘어선다.

이건 README가 프레임워크에 남는다고 한 영역과 정확히 겹친다.

즉, 우리 .claude 구조를 GitAgent로 전부 대체하는 건 현실적이지 않다.

대체보다 “정리 레이어”로 덧대는 쪽이 맞다.

아래처럼 보면 이해가 쉽다.

우리 `.claude` 요소	GitAgent에서 잘 맞는 위치	그대로 남는 것
`agents/*.md`의 정체성/톤	`SOUL.md`	세부 런북, 긴 작업 절차
에이전트 메타/권한/역할	`agent.yaml`	런타임별 세부 옵션
`.claude/skills/*`	`skills/`	실행 스크립트 호환성 조정
`.claude/rules/*`	`RULES.md`, `compliance/`, `workflows/`	채널별 세밀한 운영 규칙
`.claude/MEMORY/*`	`memory/`	실제 읽기/쓰기 정책과 충돌 해결
MCP/툴 스키마	`tools/`	라이브 호출 어댑터
하네스 코드	일부 `hooks/` 참고 정도	대부분 별도 유지

여기서 핵심은 이거다.

GitAgent는 우리 구조를 “얇고 표준적인 정의층”으로 재표현하는 데 유용하다.

특히 외부 툴로 export하거나, 다른 런타임과 공유하거나, 새 팀원이 구조를 이해하게 할 때 좋다.

하지만 우리 워크스페이스의 운영력은 하네스와 스크립트, 시트 동기화, 런타임 계약에서 나온다.

그 부분은 GitAgent 문법만으로는 안 채워진다.

그래서 내가 GitAgent를 여기 붙인다면 이렇게 할 것 같다.

첫 단계.

대표 에이전트 하나를 뽑는다.

예를 들어 blog-idea-capture나 blog-writer 같은 명확한 역할의 워커다.

둘째.

기존 md에서 정체성만 SOUL.md로 분리한다.

셋째.

현재 사용하는 스킬과 권한, 금지 규칙, 역할을 agent.yaml에 묶는다.

넷째.

.claude/skills 중 공용화 가능한 것만 skills/ 개념으로 정리한다.

다섯째.

하네스는 건드리지 않는다.

여기서 욕심내서 하네스까지 한 번에 포팅하면 거의 반드시 삐끗한다.

즉, GitAgent는 전체 갈아엎기보다 “정의 정리용 어댑터”로 쓰는 게 현실적이다.

이렇게 보면 꽤 쓸만하다.

브랜치, PR, diff로 에이전트를 운영할 때 좋아지는 점

GitAgent 얘기에서 제일 실용적인 포인트는 사실 파일 포맷보다 협업 방식이다.

공식 README가 branch, PR, versioning, audit를 계속 말하는 이유가 있다.

에이전트는 이상하게도 팀 자산인데 팀 프로세스 밖에서 관리되는 경우가 많다.

누가 시스템 프롬프트를 고쳤는지 모른다.

왜 성격이 바뀌었는지 기록이 없다.

스킬 추가가 언제부터 품질을 흔들었는지 추적이 안 된다.

그런데 Git 안으로 들어오면 얘기가 달라진다.

첫째, 리뷰가 쉬워진다.

예를 들어 SOUL.md에서 “더 공격적으로 답하기” 같은 변경이 들어오면 그건 바로 사용자 경험 리스크다.

PR로 보면 팀이 멈춰 세울 수 있다.

둘째, 롤백이 쉬워진다.

에이전트가 이상하게 변했을 때 사람들은 보통 원인을 빨리 못 찾는다.

근데 설정과 정체성이 커밋으로 남아 있으면 바로 되돌릴 수 있다.

셋째, 환경 분리가 쉬워진다.

README가 말한 branch-based deployment를 쓰면 dev, staging, main 흐름으로 에이전트 변화를 승격시킬 수 있다.

프롬프트 수정도 실험 브랜치에서 먼저 검증하고 production으로 올릴 수 있다.

넷째, 감사 흔적이 남는다.

특히 역할 분리나 규정 준수가 중요한 팀은 이게 중요하다.

누가 maker고 누가 checker인지, 어떤 정책을 누가 승인했는지, 변경 이력과 검토 흔적이 남으면 설명 가능성이 올라간다.

다섯째, 협업 언어가 단순해진다.

“대시보드 들어가서 거기 있는 hidden prompt 열고 복붙해봐” 같은 말이 사라진다.

“이 PR에서 SOUL.md 14번째 줄이 좀 과하다”라고 말할 수 있다.

이건 별거 아닌 것 같아도 진짜 크다.

운영팀 스트레스를 많이 줄인다.

다만 비용도 있다.

문서 리뷰 비용이다.

에이전트가 많아질수록 PR도 많아진다.

둘째는 합의 비용이다.

정체성과 권한을 명시하면 팀원끼리 논쟁이 생긴다.

오히려 지금까지는 문서가 없어서 대충 넘어가던 걸 이제는 합의해야 한다.

셋째는 저장소 청결 비용이다.

메모리까지 Git으로 다루면 노이즈가 늘 수 있다.

README는 live agent memory 패턴도 이야기하지만, 모든 메모리를 Git에 그대로 커밋하는 건 팀에 따라 귀찮을 수 있다.

넷째는 운영 속도 저하다.

작은 수정도 리뷰를 태우면 체감상 느려진다.

그래서 모든 에이전트에 같은 수준의 PR 통제를 거는 건 비효율적일 수 있다.

내 추천은 이렇다.

사고 비용이 큰 에이전트부터 GitAgent 철학을 강하게 적용한다.

예를 들어 게시, 결제, 배포, 데이터 변경 같은 걸 건드리는 에이전트다.

반대로 탐색형 아이디어 캡처나 개인 보조 에이전트는 좀 더 가볍게 간다.

한마디로 “중요도별 PR 강도 조절”이 필요하다.

모든 걸 컴플라이언스 급으로 운영하면 팀이 지친다.

실수 TOP 5

1. GitAgent를 런타임 대체재로 오해하는 실수

제일 흔한 착각이다.

GitAgent는 정의와 버전 관리 쪽에 강하다.

하지만 장기 루프, 상태 머신, 실제 툴 실행, 재시도 정책, 실패 복구까지 대신해주진 않는다.

공식 README도 이건 프레임워크에 남는다고 적는다.

이걸 무시하고 “이제 표준 생겼으니 다 해결”이라고 생각하면 바로 실망한다.

2. `SOUL.md`에 모든 걸 욱여넣는 실수

정체성 문서는 말 그대로 정체성이어야 한다.

성격, 가치, 커뮤니케이션, 상호작용 스타일이 중심이어야 한다.

근데 여기에 운영 절차, 배포 정책, API 제약, 파일 경로, 예외 규칙을 다 몰아넣으면 다시 스파게티가 된다.

그건 그냥 큰 프롬프트 파일 하나를 되살리는 거다.

SOUL.md는 인격이다.

런북이 아니다.

3. `agent.yaml`을 선언만 하고 검증하지 않는 실수

공식 흐름에도 gitagent validate가 들어간 이유가 있다.

manifest는 적어놓는 것보다 맞는지 보는 게 중요하다.

역할 분리나 권한 모델, 어댑터 export 전에 구조 검증이 없으면 문서만 그럴싸해진다.

말만 표준이고 실제론 틀어져 있는 상태가 제일 위험하다.

4. 모든 메모리를 Git에 그대로 싣는 실수

README는 live memory 패턴을 제안하지만, 팀에 따라선 noise가 된다.

하루 로그, 실행 중간 상태, 잔메모까지 전부 커밋하면 diff가 너무 시끄러워진다.

리뷰 효율이 뚝 떨어진다.

정말 남겨야 할 의사결정과 장기 문맥만 버전 관리 대상으로 남기는 편이 현실적이다.

5. 이식성 기대치를 너무 높게 잡는 실수

공식 사이트가 framework-agnostic을 강조하는 건 맞다.

근데 그건 “정의 레벨에서의 개방성”에 더 가깝다.

Claude Code와 OpenAI Agents SDK, CrewAI가 런타임 동작까지 똑같아지는 건 아니다.

도구 모델, 컨텍스트 주입 방식, 훅, 메모리 정책은 여전히 다르다.

그래서 export는 쉬워질 수 있어도, 운영 등가성까지 자동 보장되진 않는다.

이 기대치를 낮추면 만족도가 올라간다.

언제 아직 부족한가

여기서부터가 진짜 중요하다.

좋은 얘기만 하면 또 도구 소개글이 된다.

GitAgent가 지금 당장 부족하게 느껴질 수 있는 지점은 꽤 명확하다.

첫째, 런타임 추상화는 아직 완전한 마법이 아니다.

공식 사이트는 여러 프레임워크로 export 가능하다고 말한다.

좋다.

근데 실전에서는 각 런타임이 요구하는 실행 규약이 다르다.

툴 호출 흐름도 다르고, 메모리 지속 방식도 다르고, 스레드 개념도 다르고, 실패 처리 방식도 다르다.

정의가 통일돼도 체감 동작은 달라질 수 있다.

둘째, 하네스 친화성은 별도 작업이 필요하다.

우리처럼 일일 배치, 백필, 재검증, 상태 저장, 복구 루프가 중요한 팀은 GitAgent만으로 부족하다.

README가 hooks/를 제안하긴 하지만, 그건 실행 전후 제어에 가깝다.

운영 하네스 전부를 대체하진 않는다.

셋째, 문서 설계 역량이 부족하면 오히려 품질이 떨어질 수 있다.

표준 포맷이 생겼다고 문서가 저절로 좋아지진 않는다.

SOUL.md가 흐릿하면 에이전트도 흐릿해진다.

agent.yaml이 뭉뚱그려져 있으면 통제도 흐릿해진다.

넷째, 작은 팀에는 과할 수 있다.

혼자 실험하는 사람은 그냥 로컬 프롬프트 한 장으로 더 빨리 갈 수 있다.

굳이 branch, PR, compliance, audit까지 얹으면 준비 운동만 하다 하루 간다.

다섯째, 툴링 성숙도는 아직 지켜봐야 한다.

2026년 3월 26일 기준 공식 사이트의 구조화 데이터에는 softwareVersion이 0.1.0으로 들어가 있다.

초기 버전이라는 뜻이다.

초기 버전이 나쁘다는 건 아니다.

다만 “회사를 전부 여기에 올인”하기 전에 작은 파일럿으로 검증하는 게 맞다.

여섯째, 표준 전쟁은 늘 있다.

개방형 표준은 멋있다.

근데 실제로는 각 런타임과 벤더가 저마다 조금씩 다른 요구를 가진다.

그래서 장기적으로 얼마나 넓게 수용될지는 계속 봐야 한다.

표준이 이긴다고 해도, 로컬 관성은 오래 남는다.

즉, GitAgent는 재밌고 쓸모 있는 시도다.

하지만 2026년 3월 시점에선 “당장 모든 걸 갈아탈 대세 엔진”보다는 “잘 설계된 정의 표준 후보”에 더 가깝다.

이 위치를 정확히 이해해야 한다.

언제 이 선택이 맞고, 언제 아닌가

이제 선택 기준을 딱 잘라보자.

이런 팀이면 맞다

에이전트 정의가 여러 곳에 흩어져 있어서 리뷰가 힘든 팀
Claude, OpenAI, CrewAI처럼 런타임 이식성 고민이 있는 팀
사람 리뷰, 브랜치, PR, 감사 흔적이 중요한 팀
maker, checker, executor처럼 역할 분리가 필요한 팀
모노레포 안에서 공용 스킬과 공용 컨텍스트를 재사용하고 싶은 팀
“에이전트도 소프트웨어처럼 관리하자”는 문화가 있는 팀

이런 팀이면 아직 아니다

혼자 로컬에서 빠른 프로토타입만 만드는 사람
정의보다 실행 안정성과 복구 루프가 더 급한 팀
PR 리뷰 비용을 감당하기 어려운 작은 팀
벤더별 런타임 세부 조정이 더 중요한 팀
문서보다 코드와 스크립트에서 실제 품질이 갈리는 팀

내 추천은 이렇다.

처음부터 모든 에이전트를 GitAgent로 바꾸지 마라.

대표 워커 하나만 뽑아서 시작해라.

정체성이 분명하고, 협업 이점이 있고, 런타임 복잡도가 너무 높지 않은 워커가 좋다.

예를 들면 리뷰어, 리서처, 문서 작성기, 아이디어 분류기 같은 역할이다.

반면 하네스 중심 운영자나 긴 복구 루프를 가진 워커는 나중으로 미루는 게 좋다.

그리고 파일럿 목표도 좁게 잡는 게 좋다.

“이식성 검증” 하나.

“PR 리뷰 가능성 개선” 하나.

“온보딩 단순화” 하나.

이 정도면 충분하다.

이 글을 읽는 사람이 AI 개발 워크플로를 이미 굴리고 있다면, 먼저 Codex for Software Engineers 2026 — 자동완성 다음 단계, 병렬 위임형 코딩 에이전트 체크리스트도 같이 보면 좋다.

여기서 말하는 병렬 워커 운영과 GitAgent의 역할 분리 관점이 꽤 잘 이어진다.

툴 호출 안정성 쪽이 더 고민이라면 AI 에이전트 자동화가 덜 깨지게 만드는 CLI 설계 2026 — JSON 입력·schema·dry-run 체크리스트도 연결해서 보는 편이 낫다.

GitAgent가 정의 레이어를 다듬는다면, 저 글은 실행 인터페이스를 덜 깨지게 만드는 쪽이다.

코드 리뷰 협업 루프까지 붙이고 싶다면 풀 리퀘스트는 죽었다 2026 — 리뷰어 코멘트를 AI가 직접 받는 MCP 코드리뷰 워크플로 체크리스트도 같이 보면 그림이 더 선명해진다.

즉, GitAgent는 혼자서 모든 걸 해결하는 주인공보다, 정의와 협업 레이어를 정리해주는 조연에 가깝다.

근데 좋은 조연은 생각보다 오래 간다.

FAQ

Q1. GitAgent는 에이전트 런타임인가, 아니면 표준인가?

지금 시점에 더 가까운 표현은 “개방형 정의 표준 + CLI 도구”다.

공식 사이트는 define, version, run을 모두 말하지만, 공식 README는 무엇이 여전히 프레임워크 몫인지도 분명히 적어둔다.

그래서 런타임 전체를 대체하는 제품이라기보다, 에이전트를 Git 안에서 정의하고 검증하고 export하는 레이어로 이해하는 편이 정확하다.

Q2. 진짜 필수 파일은 `agent.yaml`과 `SOUL.md` 두 개뿐인가?

공식 README 기준으로는 그렇다.

README가 “Only two files are required”라고 적어두고, manifest인 agent.yaml과 identity인 SOUL.md를 최소 구조로 제시한다.

다만 실전에서는 skills/, tools/, workflows/, memory/ 같은 보조 구조가 금방 필요해질 가능성이 높다.

둘로 시작할 수는 있어도 둘로 끝나는 경우는 드물다.

Q3. 우리처럼 `.claude` 구조가 이미 있으면 굳이 GitAgent가 필요한가?

필수는 아니다.

이미 잘 굴러가는 구조라면 더더욱 그렇다.

다만 정의를 표준적인 manifest + identity 조합으로 얇게 정리하고 싶다면 의미가 있다.

특히 외부 런타임으로 export하거나, 새 팀원 온보딩을 단순화하거나, 에이전트 변경을 Git PR로 엄격하게 보고 싶다면 쓸만하다.

Q4. Claude Code에서 쓰던 에이전트를 OpenAI 계열로 바로 옮길 수 있나?

정체성과 구조를 옮기는 건 쉬워질 수 있다.

공식 사이트 FAQ도 여러 프레임워크 export를 말한다.

하지만 실제 도구 호출 규약, 메모리, 루프, 훅, 상태 관리는 런타임마다 달라서 추가 조정이 필요할 가능성이 높다.

즉, “복붙 후 동일 동작” 기대는 낮추는 게 맞다.

Q5. GitAgent의 가장 큰 장점 하나만 꼽으면 뭐가 제일 큰가?

나는 리뷰 가능성이라고 본다.

에이전트 정체성과 설정이 파일로 남고, 브랜치와 PR로 바뀌면 팀이 드디어 에이전트를 소프트웨어처럼 다룰 수 있다.

누가 뭘 바꿨는지, 왜 바꿨는지, 언제 되돌릴 수 있는지가 명확해진다.

이건 벤더 락인보다도 매일 체감되는 장점이다.

Q6. 가장 큰 단점은 뭔가?

운영 부담이다.

문서 품질을 유지해야 하고, 리뷰 비용이 들고, 런타임 문제는 따로 해결해야 한다.

즉, 혼돈을 없애는 대신 관리 책임을 드러내는 도구다.

작은 팀엔 이게 귀찮게 느껴질 수 있다.

Q7. 설치 후 제일 먼저 해볼 명령은 뭐가 좋나?

공식 사이트 FAQ 흐름대로면 이 순서가 무난하다.