AI 코딩 에이전트에 회사의 일하는 법을 넣는 방법 — 5개 기업 사례
카카오, 토스, OpenAI, Meta, Cloudflare의 공개 사례로 조직 지침, 저장소 컨텍스트, 역할별 워크플로, CI 검증을 짧고 쉽게 정리합니다.
AI 코딩 에이전트에 회사의 일하는 법을 넣는 방법 — 5개 기업 사례 슬라이드
코딩 에이전트는 비슷한 코드를 찾고 새 코드를 만드는 데 능숙합니다. 하지만 이 회사에서 결제 상태를 어떻게 나누는지, 어떤 모듈이 원장 데이터를 소유하는지, 배포 전에 어떤 검사를 통과해야 하는지는 저절로 알지 못합니다.
그래서 필요한 것은 더 긴 프롬프트가 아니라 회사의 일하는 법을 에이전트가 찾고, 필요한 범위에서 읽고, 결과로 검증받는 구조입니다. 공개 근거가 분명하고 운영 방식이 서로 다른 다섯 사례만 골라 핵심을 정리했습니다.
먼저 세 가지만 구분하자
| 구분 | 답하는 질문 | 예시 |
|---|---|---|
| 지침 | 어떻게 작업해야 하는가? | 새 API에는 테스트를 추가한다 |
| 컨텍스트 | 왜 그렇고 어디에 적용되는가? | 결제 원장은 이 모듈만 수정한다 |
| 검증 게이트 | 실제로 지켰는가? | test, linter, 보안 검사, PR 승인 |
지침과 컨텍스트는 에이전트의 판단을 돕지만 강제력은 없습니다. 반드시 지켜야 하는 규칙은 test와 CI가 판정해야 합니다. 이 구분만 기억해도 문서에 둘 내용과 자동화할 내용을 쉽게 나눌 수 있습니다.
공개 사례는 다섯 곳이면 충분하다
1. 토스 — 저장소에서 바로 읽는 작업 규칙
토스의 공개 저장소 es-toolkit에는 실제 AGENTS.md가 있습니다. 프로젝트 구조, 구현 순서, test, lint, typecheck 명령과 PR 형식이 들어 있습니다. runtime dependency를 추가하지 말 것, 새 함수에는 benchmark를 붙일 것, public API가 바뀌면 여러 언어의 문서를 함께 고칠 것처럼 결과를 확인할 수 있는 규칙이 중심입니다.
apps-in-toss-ax는 개발자 문서와 예제를 에이전트가 조회할 수 있도록 MCP 문서 서버를 제공합니다. 짧은 루트 지침에는 작업 방법을 두고, 양이 많거나 자주 바뀌는 지식은 필요할 때 도구로 가져오는 방식입니다. 공개 저장소의 사례이므로 토스 전사의 단일 표준으로 확대해서 읽어서는 안 됩니다. es-toolkit 지침, 문서 MCP
2. OpenAI — 루트 문서는 목차로만 쓴다
OpenAI가 공개한 특정 내부 제품 사례에서는 큰 AGENTS.md가 작업 컨텍스트를 너무 많이 차지하고 빠르게 낡았습니다. 팀은 이를 약 100줄의 지도로 줄이고, 설계, 실행 계획, 제품 명세, 품질과 보안 문서를 docs/에 나눴습니다.
linter와 CI는 문서 링크와 구조를 검사하고, 코드와 어긋난 설명은 별도 에이전트가 찾아 수정 PR을 만듭니다. 의존 방향이나 logging 같은 불변식은 구조 test와 linter로 강제합니다. 항상 읽히는 파일은 짧게, 상세 지식은 별도 문서로, 강제 규칙은 코드로 나눈 사례입니다. OpenAI Harness Engineering
3. Meta — 사람 머릿속 규칙을 작은 컨텍스트로 나눈다
Meta가 공개한 특정 데이터 파이프라인은 네 개 저장소, 세 언어, 4,100개가 넘는 파일로 구성돼 있었습니다. 에이전트는 코드를 읽을 수 있었지만 삭제하면 안 되는 enum이나 단계 사이에서 바뀌는 field 이름처럼 사람만 아는 규칙을 놓쳤습니다.
Meta는 이 지식을 59개의 짧은 파일로 나눴습니다. 각 파일은 25~35줄이며 실행 명령, 핵심 파일, 숨은 규칙, 관련 문서를 담습니다. 필요할 때만 읽게 하고, 여러 critic과 정기 검사가 내용과 경로의 최신성을 확인합니다. 예비 평가에서는 도구 호출과 token 사용이 약 40% 줄었습니다. 작게 나누고, 필요한 곳에서만 읽고, 계속 검증하는 방식입니다. Meta의 구조화된 컨텍스트 사례
4. 카카오 — 원칙과 서비스별 배포 검사를 연결한다
카카오 공식 GitHub에는 코딩 에이전트와 협업하기 위한 6개 원칙과 28개 실천 방법이 공개돼 있습니다. 개발자의 최종 책임, 생성 코드의 이해와 검증, 기밀성, 팀 coding standard와 architecture 일관성을 강조합니다.
배포 리스크 검토 서비스 KRIS는 diff를 과거 장애에서 만든 정책과 대조합니다. 규칙 위반처럼 같은 입력에 같은 답을 낼 수 있는 부분은 판정 로직이 맡고, 위험도는 LLM이 문맥을 보고 판단합니다. 전사 공통 규칙과 서비스 전용 규칙도 분리합니다. 원칙은 문서로 설명하고, 지역 지식은 범위를 좁히며, 반복 판정은 코드로 실행하는 구조입니다. 카카오 원칙 문서, KRIS 개발기
5. Cloudflare — 공통 기준과 저장소 규칙을 함께 운영한다
Cloudflare는 5,000개가 넘는 저장소에서 동작하는 CI 기반 AI code review를 공개했습니다. 조직 공통 규칙은 중앙 template으로 관리하고, 각 팀은 저장소의 AGENTS.md로 project-specific instruction을 추가합니다.
security, performance, code quality, documentation 같은 specialist reviewer가 나눠서 검사하고 coordinator가 결과를 합칩니다. 별도 검사는 build tool이나 directory 구조가 바뀌었는데 지침이 그대로인지 확인합니다. 중앙 정책, local rule, 역할별 review, CI, 지침 최신성 검사를 한 흐름으로 연결한 사례입니다. Cloudflare의 대규모 AI code review
다섯 사례를 합치면 5계층이 된다
| 계층 | 담을 내용 |
|---|---|
| 1. 조직 정책 | 보안, 개인정보, 승인 규칙, 허용 도구 |
| 2. 저장소 지도 | 제품 목적, 주요 directory, build와 test 명령, 문서 링크 |
| 3. local context | 서비스 domain, 경로별 규칙, 설계 결정과 예외 |
| 4. 역할별 workflow | 구현, review, test, debugging 절차와 도구 |
| 5. 검증 게이트 | test, linter, static analysis, PR과 release 검사 |
항상 읽히는 것은 짧은 저장소 지도까지면 충분합니다. local context와 workflow는 작업 대상과 역할이 맞을 때만 읽습니다. 검증 게이트는 모델의 판단에 기대지 않고 실제 결과를 판정합니다.
파일은 이 정도면 시작할 수 있다
AGENTS.md # 짧은 지도와 필수 명령
docs/
├── architecture.md # 시스템 경계와 의존 방향
├── decisions/ # 설계 결정과 이유
└── services/ # 서비스별 domain과 운영 규칙
agent-workflows/
├── code-review.md
├── testing.md
└── debugging.md이 이름을 그대로 따를 필요는 없습니다. 루트 파일이 실제 원본 문서를 가리키는지, 서비스 규칙이 다른 영역에 적용되지 않는지, 반복 절차를 다시 실행할 수 있는지, CI가 강제할 항목이 분리돼 있는지가 더 중요합니다.
도입은 네 단계면 충분하다
- 최근 code review 지적, build failure, rollback과 incident 10건을 모읍니다.
- 몰라서 틀린 내용은 context에, 반복 절차는 workflow에, 항상 같은 판정이 가능한 규칙은 CI에 둡니다.
- code review나 test generation처럼 측정하기 쉬운 역할 하나부터 시작합니다.
- 각 규칙에 owner, 적용 범위, 원본 문서와 마지막 검증일을 남기고 낡은 링크와 명령을 정기적으로 찾습니다.
초기에는 자동 수정이나 merge 차단보다 advisory comment가 안전합니다. false positive와 수정 수용률을 기록한 뒤 권한을 넓히면 어디서 품질이 무너지는지 알 수 있습니다.
실패하기 쉬운 네 가지
- 루트 지침을 모든 지식이 들어 있는 백과사전으로 만든다.
- 한 서비스의 예외 규칙을 모든 저장소에 적용한다.
- 반드시 막아야 할 행동을 prompt 문장에만 맡긴다.
- 규칙의 owner와 최신성 검사를 두지 않는다.
좋은 조직 지침은 문서가 많은 상태가 아닙니다. 에이전트가 필요한 정보를 짧은 경로로 찾고, 자신의 작업 범위에 맞는 지식만 읽으며, 결과가 자동 검사되는 상태입니다.
참고 자료
- 카카오, Agentic Coding Principles & Practices
- 카카오, KRIS 개발기
- 토스, es-toolkit AGENTS.md
- 토스, apps-in-toss-ax CLAUDE.md
- OpenAI, Harness engineering
- Meta, How Meta Used AI to Map Tribal Knowledge
- Cloudflare, Orchestrating AI Code Review at scale
한 문장으로 정리하면
짧은 루트 문서는 지식의 위치를 안내하고, local context는 판단의 이유를 설명하며, 역할별 workflow는 반복 작업을 표준화하고, test와 CI는 결과를 강제합니다. 이 네 가지가 연결되면 특정 모델이나 도구가 바뀌어도 회사의 일하는 법은 저장소와 개발 플랫폼 안에 남습니다.