Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
사내 지식 기반(Company Brain)이 AI 에이전트 시대에 맞춰 Markdown과 YAML이라는 일반 텍스트 형식으로 수렴하고 있습니다. 본문 내용은 가독성이 좋은 Markdown으로, 문서의 메타데이터와 구조는 YAML로 분담하는 것이 가장 효율적입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기사내 지식은 YAML과 Markdown이라는 두 가지 일반 텍스트 형식으로 수렴하게 될 것이다. 이 글의 주장은 여기에 있다.
지금까지는 '모든 업무는 Skill에 기록하라'라며 절차를 SKILL.md로 작성하도록 권장했고, mdschema에서는 Markdown 구조를 YAML 스키마로 검증하는 도구를 만들었다. 돌이켜보면 둘 다 Markdown을 중심으로 하고 YAML을 보조하고 있다. 본고는 그 배경에 깔린 생각을 언어화한 것이다.
지금까지의 사내 지식은 사람이 읽는 것을 전제로 했다. 사내 Wiki도, Notion도, 공유 드라이브의 Word 파일도 마지막 독자는 인간이었다.
하지만 지금은 다르다. AI 에이전트가 절차서를 읽고, 방침을 참조하며, 과거의 의사결정을 바탕으로 업무를 수행한다. 본고에서는 이러한 AI가 참조하는 회사 전체 지식 기반을 '컴퍼니 브레인(Company Brain)'이라고 부른다. 이 용어는 2026년경부터 영어권에서 사용되기 시작했다. 선행 사례를 보아도 Andrej Karpathy의 LLM Wiki는 Markdown 리포지토리 자체를 지식 저장소로 삼았고, Garry Tan의 GBrain 역시 Markdown 리포지토리를 색인화하여 사용한다.
독자에게 AI가 추가되면서, 어떤 도구에 배치할 것보다 어떤 형식으로 작성하는지가 더 중요해진다. 결론부터 말하자면, 본문은 Markdown, 메타데이터와 구조는 YAML로 분담하는 것이 적절하다. 하지만 이것이 회사의 모든 지식을 의미하지는 않는다. 어디까지가 수렴하고 어디부터가 수렴하지 않을지 정리하고자 한다.
에이전트용 지식은 이미 Markdown과 YAML 쪽으로 기울고 있다. Anthropic과 OpenAI가 각각 만든 형식들이 모두 Markdown을 기반으로 하고 있다.
| 형식 | 내용 | 위치 |
|---|---|---|
| CLAUDE.md | Markdown | Claude Code가 프로젝트별로 읽는 지침서 |
| ... |
특히 시사하는 바가 큰 것이 SKILL.md이다. 사양상 파일의 맨 앞에는 YAML 프런트매터(frontmatter)를, 그 뒤에 Markdown 본문을 배치하는 것이 필수적이다. 에이전트는 시작할 때 프런트매터의 이름과 설명만 읽고, 스킬 하나당 약 100 토큰으로 '무엇이 어디에 있는지'를 파악한다. 본문은 필요할 때 처음으로 불러온다.
즉, YAML로 목차를 만들고 Markdown으로 내용을 작성하는 것이다. 이 분담이 컴퍼니 브레인의 원형이 된다.
Markdown이 선택되는 이유는 사람과 AI 모두에게 '적당한' 형식이 다른 데 없기 때문이다. 그 이유는 네 가지가 있다.
Notion이나 사내 Wiki가 나쁜 것은 아니다. 다만, 그 내용을 AI에게 전달할 때 결국 Markdown으로 추출하는 경우가 많다. 그렇다면 처음부터 Markdown으로 보유하는 것이 빠르다.
YAML은 본문을 작성하기 위한 형식이 아니다. 컴퍼니 브레인에서 YAML의 역할은 문서에 붙이는 라벨과 조직의 골격을 정의하는 것이다.
라벨로서의 YAML. Markdown 맨 앞에 프런트매터로 배치하여, 해당 문서가 무엇인지, 누구의 것인지, 언제까지 유효한지를 작성한다.
---
title: 경비 정산 정책
owner: finance-team
...
AI는 이 라벨을 보고 만료된 문서를 제외하고, 독자에 따라 분류하며, 의문이 있으면 소유자에게 확인을 요청할 수 있다. 사람 입장에서도 신선도와 책임자가 한눈에 파악된다.
골격으로서의 YAML. 조직도, 승인 경로, 용어집, 시스템 목록처럼 글보다 항목의 집합으로 표현해야 하는 정보는 YAML 단독 파일이 적합하다.
# 승인 경로(금액 상한에 따라 승인자를 정의)
expense_approval:
-
limit: 50000
...
```}{
JSON이 아닌 YAML인 이유는 사람이 읽고 쓸 수 있기 때문이다. JSON은 괄호와 따옴표가 많고, 주석도 작성할 수 없다. YAML은 들여쓰기(indent)에 습관이 있지만, 라벨이나 목록 정도의 얕은 구조라면 문제가 되기 어렵다.
본문은 Markdown으로, 라벨과 골격은 YAML로 한다. 이 둘은 경쟁하는 것이 아니라, 하나의 파일 위에서 역할을 나누어 맡는다.
## 데이터베이스에서는 안 될까
구조화하여 보관한다면, 데이터베이스라는 방법도 있다. 다만, 사람이 정리해서 쓰는 지식의 원데이터에는 데이터베이스가 적합하지 않다. 이유는 주로 네 가지이다.
- **작성자가 한정된다.** 비엔지니어는 직접 수정할 수 없고, 누군가가 편집용 관리 화면을 만들고 계속 유지보수해야 한다. 작성 장벽이 높아지면 지식은 금방 업데이트되지 않는다. - **미리 타입을 정해야 한다.** 테이블과 컬럼을 설계한 후에 데이터를 넣어야 한다. 하지만 사내 지식에는 예외나 경위, 뉘앙스가 많아서, 타입에 담기지 않는 부분이 오히려 중요할 때가 있다. - **AI에게 전달하려면 결국 텍스트로 되돌려야 한다.** 레코드를 꺼내어 문맥이 있는 글로 정형화하는 변환 계층(conversion layer)이 필요하다. 처음부터 문서 형태로 가지고 있는 Markdown이라면, 그 수고가 없다. - **이력 및 리뷰를 직접 만들어야 한다.** 누가 왜 값을 변경했는지 추적하는 시스템도, 승인 플로우도 표준적으로 제공되지 않는다. Git이라면 둘 다 처음부터 있다.
그 외에도 서버 운영, 백업, 스키마 변경 시의 마이그레이션 작업 등 지속적인 비용이 발생한다.
반면, 데이터베이스가 더 적합한 경우도 있다. 대량의 레코드, 빈번한 업데이트, 동시 쓰기(concurrent write), 엄격한 검색 및 집계이다. 그렇기 때문에 다음에 설명할 '살아있는 데이터(動くデータ)'는 데이터베이스에 남겨두는 것이 좋다. 검색용 벡터 데이터베이스(vector database)도 유용하지만, Markdown으로 만드는 인덱스로 사용하고 원데이터로는 삼지 않는 것이 좋다.
## 수렴하지 않는 것들
다만, 회사의 지식이 모두 파일이 되는 것은 아니다. 적어도 네 가지 영역은 YAML과 Markdown 밖에 남아있다.
- **움직이는 데이터:** 고객 정보, 매출, 재고, 문의는 시시각각 변한다. 파일에 옮겨 적으면 그 순간부터 오래된다. 원래의 데이터베이스나 SaaS에 둔 채로, 필요할 때 가져오는 것이 옳다. - **세밀한 권한 관리:** '이 단락은 임원만', '이 고객 정보는 담당자만'과 같은 제어는 파일 단위의 접근 권한으로는 표현하기 어렵다. - **동시 편집:** 여러 사람이 실시간으로 같은 문서를 수정하는 경험은 Git의 강점 분야가 아니다. 회의록이나 초안은 기존 공동 편집 도구가 더 빠르다. - **규모와 관계성:** 문서가 수천, 수만 개가 되면, 파일을 순서대로 읽는 것만으로는 찾을 수 없다. 검색 인덱스나, 문서 간의 관계를 나타내는 그래프가 별도로 필요하다.
이것들까지 억지로 파일로 모으려고 하면, 컴퍼니 브레인(Company Brain)은 오래되고 부정확한 정보의 산더미가 된다. '사람이 정리해서 쓰는 지식'의 계층만 수렴한다고 받아들이는 것이 현실적인 설계이다.
## 컴퍼니 브레인의 3계층 구조
수렴하는 부분과 그렇지 않은 부분을 합치면, 컴퍼니 브레인은 세 개의 층으로 생각하면 정리하기 쉽다. YAML과 Markdown으로 작성하는 것은 왼쪽의 '쓰는 지식'만이고, 오른쪽의 살아있는 데이터는 원래 시스템에 남겨둔다. 그 사이에 위치한 계층이 늘어나는 문서를 찾는 검색(search)과 생 데이터를 그때그때 가져오는 커넥터(connector) 역할을 맡는다.
## 오늘부터 시작하려면
갑자기 전사 지식을 옮길 필요는 없다. AI에게 가장 많이 읽히고 싶은 문서부터, 작게 시작하면 된다.
- 대상을 하나 정한다: 문의 대응 절차서, 경비 규정, 온보딩 자료 등, AI에게 자주 질문할 것 같은 것을 고른다. - Markdown으로 작성하고 Git 리포지토리에 둔다: 기존 Wiki나 Notion에서 내보내기(export)만 해도 충분하다. - 프론트매터 항목을 최소화한다: 우선 `owner`, `updated`, `review_by` 세 가지만. 항목을 늘리는 것은 운영이 돌아간 후에 해도 좋다. - AI 에이전트에게 읽게 테스트한다: 실제 질문을 던져보고, 답할 수 없는 부분이나 오래된 기술을 찾아낸다. - 변경 사항을 리뷰로 돌린다: 절차가 바뀌면 소유자가 승인한 후에 반영한다. 이 습관이 자리 잡으면, 지식은 자연스럽게 새롭게 유지된다.
## 파일로 만든 후에도 남는 과제
파일로 모아도 문제가 모두 사라지는 것은 아니다. YAML은 무엇이든 쓸 수 있기 때문에, `approver: cfo`를 `cf0`으로 오타내도 아무도 알아차리지 못한다. '리뷰 기한을 지난 문서를 전부 보여주기'와 같은 가로지르는 검색이나 집계에는 스크립트가 필요하다. Markdown 자체는 누구나 쓸 수 있지만, Git에서 브랜치를 쳐서 리뷰에 올리는 흐름은 엔지니어 외 사람에게 익숙하지 않은 작업이다.
## 끝으로
지식을 어떤 형식으로 보유할지는 Markdown과 YAML로 결정되고 있다. 부족한 것은, 파일 상태 그대로 검증하고 찾을 수 있으며 엔지니어 외의 사람도 편집할 수 있는 도구다. 컴퍼니 브레인(Company Brain)의 다음 과제는 바로 그곳에 있다.
## 출처
- OpenAI가 Linux Foundation 산하 Agentic AI Foundation 공동 설립 (OpenAI)
- Linux Foundation, Agentic AI Foundation 결성 발표 (Linux Foundation)
- Agent Skills Specification (agentskills.io)
- LLM Wiki (Andrej Karpathy)
- GBrain (Garry Tan)
### 토론
