AI를 위한 인프라: 형상 관리는 왜 "사람이 보기 좋은 형태"에서 "AI가 이해하기 좋은 형태"로 옮겨가는가

안녕하세요, TeamH4C의 D4C Shucream입니다.

디지털 포렌식과 침해사고 대응(DFIR) 실무자로 처음 활동을 시작했고, 지금은 기업의 블루팀에서 일하고 있습니다.

이 글을 쓰게 된 계기는 단순합니다. 최근 업무에 AI를 붙여 쓰면서, AI의 능력 자체보다 그 능력을 온전히 쓰기 위해 우리가 최적화할 수 있는 부분이 무엇인가에 자연스럽게 집중하게 됐습니다. 그 고민을 한 번 정리해보고 싶었습니다.

병목은 모델이 아니라 컨텍스트입니다

AI에게 업무를 맡겨본 분이라면 한 번쯤 겪었을 장면이 있습니다.

코드 자체는 곧잘 이해합니다. 그런데 "이 설정은 왜 이 값인지", "이 서비스는 어떤 절차로 배포되는지"처럼 코드 밖의 맥락이 필요해지는 순간부터 답이 흐려집니다. 그 맥락이 위키와 메신저 스레드와 누군가의 머릿속에 흩어져 있어서, AI가 읽을 수 있는 곳에 없기 때문입니다.

모델이 부족해서가 아닙니다. 필요한 정보가 AI가 접근할 수 있는 형태로 존재하지 않았을 뿐입니다.

지난 몇 년간 우리는 "더 좋은 모델"에 투자해왔습니다. 그런데 실제 결과물의 품질 편차를 만드는 변수는 모델 쪽에서 빠르게 포화되고 있고, 남은 변수는 대부분 입력 쪽에 있습니다. 문제는 추론 능력이 아니라 컨텍스트 공급 인프라입니다.

그리고 이것은 결국 속도의 문제입니다.

AI가 개발 속도를 끌어올리면서 코드가 바뀌는 주기도, 결정이 뒤집히는 주기도 눈에 띄게 짧아졌습니다. 지식의 반감기가 줄어든 것입니다. 지식이 이 속도로 생겨나고 낡아가면, 지식 베이스는 두 구간에서 병목이 됩니다.

적재 시간: 일어난 일이 문서가 되기까지 걸리는 시간
인출 시간: 필요한 사람과 에이전트가 그 문서를 꺼내오기까지 걸리는 시간

분기에 한 번 아키텍처가 바뀌던 시절에는 이 두 시간이 길어도 버틸 수 있었습니다. 지금은 적재가 느리면 문서가 쓰이기도 전에 낡고, 인출이 느리면 에이전트가 문서 없이 추측으로 일합니다.

여기에 한 가지 현실을 더하면 방향은 분명해집니다. 조직의 지식 베이스는 이미 한 사람이 전부 파악할 수 있는 규모를 넘었습니다. 그렇다면 사람이 직접 찾는 경로를 최적화하기보다, 애초에 AI가 입력으로 받기 좋게 설계하고 AI가 가져온 답을 사람이 검증하는 구조가 낫습니다. 답을 처음부터 찾아내는 것보다, 가져온 답이 맞는지 확인하는 것이 훨씬 빠르기 때문입니다.

이 글의 주장은 결국 한 문장입니다.

형상 관리를 AI가 이해하기 좋은 형태로 옮기는 것은, 이 두 시간을 효율적으로 단축할 수 있는 가성비 좋은 방법입니다.

이 글에서 형상 관리는 소스 코드에 한정하지 않고, 문서·다이어그램·정책처럼 조직 지식 전반의 버전과 이력을 관리하는 일을 넓게 가리킵니다.

이 글은 그 이관을 어떻게 할 것인가에 대한 이야기입니다. 동시에 옮기면서 무엇이 깨지는가에 대한 이야기이기도 합니다. 무엇이 깨지는지는 빼놓고 좋은 점만 말하는 글이 너무 많기 때문입니다.

코드베이스는 이미 "AI가 이해할 수 있는 정책"을 갖고 있습니다

흥미로운 점은, 소프트웨어 조직이 이미 이 문제를 한 영역에서는 풀어두었다는 것입니다. 바로 코드베이스입니다.

.eslintrc, ruff.toml, tsconfig.json, GitHub Actions 워크플로, Terraform 모듈, OPA/Rego 정책, CODEOWNERS, .editorconfig, pre-commit 훅, 그리고 최근의 CLAUDE.md / AGENTS.md. 이것들은 전부 "우리 조직이 코드를 어떻게 다루는가"에 대한 정책입니다. 그리고 공통점이 네 가지 있습니다.

평문 텍스트입니다. 별도의 렌더링 계층이나 API 없이 바로 읽힙니다.
버전 관리됩니다. 무엇이 언제 왜 바뀌었는지가 diff와 커밋 메시지로 남습니다.
선언적입니다. 해석의 여지가 좁고, 같은 입력에 같은 결론이 나옵니다.
실행 가능합니다. 문서와 실제 동작이 갈라지면 CI가 깨집니다. 드리프트가 자동으로 검출됩니다.

이 네 가지는 우연히도 LLM이 가장 잘 읽고 활용할 수 있는 형태와 정확히 겹칩니다.

여기서 한 가지는 분명히 해두고 싶습니다. 우리는 AI를 위해 이것을 만든 것이 아닙니다. 사람과 자동화를 위해 만들었습니다. 검색되고, 리뷰되고, 이력이 남고, 자동 검증되는 자산은 AI 이전에도 이미 더 나은 자산이었습니다.

AI는 새로운 요구사항을 만든 것이 아니라, 기존 요구사항의 우선순위를 바꿨을 뿐입니다.

프롬프트를 깎아 다듬는 사람들이 생겨났던 것을 떠올려보면 자연스러운 흐름입니다. AI에게 주는 한 번의 입력을 다듬는 것이 프롬프트 엔지니어링이었다면, 이제는 AI가 입력으로 받는 데이터 소스 자체를 개선해야 하는 시점이 왔다고 생각합니다.

그런데 조직 지식의 적지 않은 부분은 아직 AI가 읽기 어려운 형태입니다

문제는 코드 바깥입니다.

물론 모든 기업이 그렇다는 것은 아닙니다. 문서화 체계가 잘 잡힌 조직도 있고, 조직마다 정도의 차이가 큽니다. 다만 일부라도 이런 모습을 갖고 있는 조직은 어렵지 않게 찾을 수 있습니다. 아키텍처는 다이어그램 툴에서 뽑은 이미지로, 배포 절차는 위키 페이지에, 결정의 근거는 메신저 스레드에, 서비스 목록은 스프레드시트에, 위협 모델은 발표용 슬라이드에 있는 모습 말입니다.

다이어그램 이미지를 예로 들어보겠습니다. 이미지 안에 정보가 없는 것은 아닙니다. draw.io는 PNG로 내보낼 때 다이어그램 XML을 이미지의 zTXt 청크에 기본으로 임베드하고, 그 PNG를 캔버스에 다시 끌어다 놓으면 그대로 편집됩니다.

그런데도 실무에서는 문제가 됩니다. 임베드된 XML은 압축·인코딩된 바이너리 청크라서 grep에 걸리지 않고, diff에도 잡히지 않으며, 코드 리뷰에서 변경점을 읽을 수 없습니다. 내보내기 옵션 하나만 꺼도 사라집니다. 위키에 첨부되는 순간 파일 시스템 경로에서 사라지고 첨부파일 ID 뒤로 숨습니다.

즉 정보가 없는 것이 아니라, 조직의 검색·리뷰·이력 관리 어디에도 포함되지 못하는 상태입니다. 접힌 토글 안의 문단, 표 안의 표, 스크린샷으로 붙인 로그, "자세한 건 아래 스레드 참고"가 전부 같은 범주입니다.

솔직해질 필요가 있습니다. 이런 부분이 있는 조직이라면, 그것은 AI 이전에도 나빴습니다. 검색이 안 되고, 리뷰를 못 받고, 조용히 낡아갑니다. AI는 이 문제를 새로 만든 것이 아니라, 이미 있던 문제를 더 빨리 드러냈을 뿐입니다.

왜 옵시디언 같은 볼트가 다시 각광받을까요

여기서 흥미로운 역전이 일어납니다. 노션이나 컨플루언스처럼 시각적으로 잘 다듬어진 도구보다, 옵시디언처럼 투박한 마크다운 볼트가 AI 워크플로에서 더 좋은 평가를 받습니다.

보기 좋아서가 아니라, 꾸미는 계층 없이 AI가 바로 읽을 수 있는 형태이기 때문입니다.

차이는 숫자로 확인됩니다. 노션은 블록을 구조화된 JSON으로 주는 공식 API가 있지만, 통합당 평균 초당 3요청으로 제한되고, 자식 블록 배열은 한 응답에 100개까지이며, 한 요청으로는 블록 트리를 2단계 깊이까지만 가져올 수 있습니다. 중첩이 깊은 페이지 하나를 온전히 수집하는 데만 수십 초가 걸립니다. 워크스페이스 단위로 확장하면 시간 단위 작업이 됩니다.

같은 일을 마크다운 볼트에서 하면 ripgrep 한 줄입니다. 이 차이는 여섯 가지 속성에서 나옵니다.

첫째, 저장 형식이 곧 교환 형식입니다. 볼트의 원본은 디스크 위의 .md 파일입니다. 조회 계층과 원본 사이에 변환이 없습니다.

둘째, 파일 시스템이 그대로 주소 체계이자 검색 엔진입니다. API 키도, 페이지네이션도, 레이트리밋도 없습니다. 에이전트가 쓸 수 있는 도구의 폭이 완전히 달라집니다.

셋째, 위키링크는 사람이 손으로 그린 지식 그래프입니다. [[제로트러스트-네트워크-설계]] 같은 링크는 임베딩 유사도가 복원하지 못하는 정보, 즉 "작성자가 의도적으로 연결한 관계"를 담습니다. 벡터 검색이 통계적 근접성을 준다면 위키링크는 명시적 간선을 줍니다. 둘은 대체재가 아니라 보완재입니다.

넷째, 프론트매터가 구조화된 메타데이터를 제공합니다. 담당자, 상태, 최종 검토일, 적용 범위를 필드로 달아두면 검색이 필터링으로 바뀝니다.

다섯째, 파일 경계가 곧 청크 경계입니다. RAG에서 눈에 잘 띄지 않게 품질을 떨어뜨리는 것이 기계적 청킹입니다. 문서 하나가 주제 하나로 정리되어 있으면 이 문제의 절반이 사라집니다.

여섯째, git과 궁합이 맞습니다. 문서에 blame이 찍히고, PR 리뷰를 받고, 이력이 남습니다. 문서가 코드와 같은 수명주기를 따르게 됩니다.

도구가 아니라 형식입니다

오해가 없도록 분명히 해두겠습니다. 이 글의 주장은 "옵시디언을 전사 도입하자"가 아닙니다.

옵시디언의 보안 모델은 애초에 팀 지식 관리를 전제로 설계되지 않았습니다. Obsidian Sync는 종단간 암호화를 제공하지만, 그 단위는 볼트 비밀번호입니다. 접근 통제의 최소 단위가 노트가 아니라 볼트 전체라는 뜻입니다.

그리고 볼트는 설계상 각 단말에 완전한 사본으로 존재합니다. 퇴사자 노트북, 분실 단말, BYOD에 조직 지식 전체의 사본이 남고, MDM 원격 소거 외에는 회수 수단이 없습니다. 종단간 암호화라 서버가 내용을 못 읽는다는 것은, 조직의 DLP도 못 읽는다는 뜻이기도 합니다.

이것은 옵시디언의 결함이 아니라 설계 목표의 차이입니다. 개인 지식 관리 도구로서는 옳은 선택입니다. 다만 그 도구를 전사 위키 대체재로 놓는 순간 통제가 느슨해집니다.

가져올 것은 도구가 아니라 형식입니다.

평문 텍스트, 파일 단위 주제, 명시적 링크, 구조화된 메타데이터, 버전 관리.

이 다섯 가지는 저장소에 그대로 구현할 수 있고, 그 위에 조직의 인증·권한·감사 통제를 얹을 수 있습니다. 옵시디언은 그 형식을 편하게 편집하는 여러 클라이언트 중 하나일 뿐입니다.

적재와 인출이 함께 빨라집니다

앞에서 말한 적재 시간과 인출 시간으로 다시 정리해보겠습니다.

보기 좋은 도구는 두 구간 모두에서 비용이 큽니다. 적재하려면 레이아웃을 잡고, 표를 그리고, 다이어그램을 그려서 붙여야 합니다. 꺼내오려면 사람이 직접 열어서 읽어야 하고, 에이전트는 레이트리밋이 걸린 API를 통과해야 합니다.

반면 마크다운과 저장소의 조합은 적재가 작업 흐름 안에 있습니다. 코드를 고친 그 PR에 문서 수정이 같이 실리고, 요즘은 초안을 에이전트가 써주기 때문에 적재 비용은 더 떨어지고 있습니다. 인출은 grep 한 번입니다.

한 가지 짚어둘 점이 있습니다. AI가 적재 비용을 낮출수록 병목은 검증으로 옮겨갑니다. 쓰는 것은 에이전트가 해줘도, 그것이 맞는 내용인지 확인하는 것은 여전히 사람의 리뷰입니다. 그래서 문서가 PR 리뷰를 거치는 형식이라는 것은 단순한 취향이 아니라, 속도를 버티게 하는 안전장치가 됩니다.

이것을 한 문장으로 줄이면 다음과 같습니다.

문서의 시각적 완성도는 사람이 한 번 읽을 때마다 편익을 줍니다. AI가 이해하기 좋은 형식은 에이전트가 한 번 호출될 때마다 편익을 줍니다.

과거에는 사람이 읽는 횟수가 압도적으로 많았고, 그래서 보기 좋은 도구에 투자하는 것이 합리적이었습니다. 에이전트가 문서를 읽는 횟수가 사람을 넘어서면 이 계산이 뒤집힙니다.

다만 이 문장은 그 자체로는 근거가 아니라 가설입니다. 이 문장만으로 도입을 결정하기보다는, 한 팀·한 저장소 같은 작은 범위에서 먼저 운영해보고 효과를 확인하는 것이 맞다고 생각합니다.

이관에 따라오는 세 가지 문제

이관에는 분명한 이점이 있지만, 동시에 세 가지 새로운 위험이 따라옵니다. 이 위험들을 먼저 정리하지 않고 시작하면 얻는 것보다 잃는 것이 더 많을 수 있습니다.

1. 문서가 에이전트를 조종하는 통로가 될 수 있습니다

지금까지의 논지는 "에이전트가 저장소의 문서를 읽게 하자"였습니다. 이 문장을 뒤집으면 이렇게 됩니다.

저장소에 쓰기 권한이 있는 사람은 누구나 에이전트의 행동을 조종할 수 있습니다.

이것은 이론이 아닙니다. 2025년 3월 Pillar Security가 공개한 Rules File Backdoor는 AI 코딩 도구의 룰 파일에 양방향 텍스트 마커와 폭 없는 결합 문자 같은 보이지 않는 유니코드로 지시를 숨겨, GitHub Copilot과 Cursor가 백도어가 포함된 코드를 생성하도록 유도했습니다. 사람에게도, PR 화면에서도 보이지 않습니다.

더 중요한 것은 벤더의 응답입니다. Cursor는 자사 플랫폼의 취약점이 아니며 위험 관리는 사용자 책임이라고 답했고, GitHub도 생성 결과의 검토 책임은 사용자에게 있다고 답했습니다. 제품 차원의 완화를 기다릴 수 없다는 뜻입니다.

같은 해 8월 패치된 CVE-2025-53773은 이 경로가 어디까지 가는지 보여줍니다. 프롬프트 인젝션으로 Copilot이 .vscode/settings.json에 chat.tools.autoApprove: true를 쓰게 만들면 사용자 승인 절차가 통째로 꺼지고, 그때부터는 셸 명령 실행이 가능해집니다. 인젝션에서 로컬 코드 실행까지 이어지는 경로입니다.

따라서 최소한 다음이 이관의 전제 조건입니다.

에이전트가 읽는 문서는 신뢰 경계 밖의 입력으로 취급합니다. 코드에서 사용자 입력을 다룰 때와 같은 수준의 주의가 필요합니다.
지침 성격의 파일(AGENTS.md, 룰 파일, 런북)은 CODEOWNERS로 보호하고 별도 승인자를 지정합니다. 일반 문서와 같은 취급을 해서는 안 됩니다.
CI에서 화면에 표시되지 않는 유니코드 문자(양방향 제어문자, 폭 없는 문자, 태그 문자)를 차단합니다. 정규식 한 줄로 구현할 수 있어, 비용 대비 효과가 확실한 기본 통제입니다.
에이전트의 쓰기 권한과 명령 실행 권한을 분리하고, 도구 자동 승인 설정 파일을 변경 감시 대상에 넣습니다.

2. 지식에 대한 권한 관리가 어려워집니다

위키는 페이지·스페이스 단위로 권한을 설정할 수 있고 열람 감사 로그도 제공합니다. 반면 git 호스팅의 권한 단위는 저장소입니다. 브랜치 보호와 경로 기반 리뷰 룰이 있지만, 이것은 쓰기 통제이지 읽기 통제가 아닙니다. 저장소를 읽을 수 있는 사람은 그 안의 모든 문서를 읽을 수 있습니다.

그런데 우리가 옮기자고 한 자산 목록에는 위협 모델, 인프라 토폴로지, 사고 대응 런북이 들어 있습니다. 이것은 조직의 방어 설계도입니다. "검색이 잘 되게" 만든다는 것은 공격자에게도 검색이 잘 되게 만든다는 뜻입니다. 개발자 계정 하나가 탈취됐을 때 rg 한 번으로 방어 구조 전체가 유출되는 구성은 만들면 안 됩니다.

그래서 이관은 한꺼번에 전부 옮기는 것이 아니라 분류 후 선별이어야 합니다.

모든 문서에 분류 등급을 메타데이터로 붙입니다. 등급 없는 문서는 CI에서 거부합니다.
등급별로 저장소를 분리합니다. 권한 경계는 저장소 경계와 일치시킵니다. 한 저장소 안에서 디렉터리로 나누는 것만으로는 읽기 통제가 되지 않습니다.
최고 등급 자산(현재 유효한 위협 모델, 미조치 취약점, 대응 플레이북)은 이관 대상에서 제외하거나, 접근 감사 로그가 있는 별도 시스템에 둡니다.
에이전트의 컨텍스트 수집 범위를 등급으로 제한합니다. 사람의 권한과 에이전트의 권한을 따로 설계합니다.

3. 한번 커밋된 시크릿은 지우기 어렵습니다

문서를 저장소로 옮기면 접속 정보, 엔드포인트, 계정 흐름, 예시 토큰이 커밋에 섞여 들어갑니다. 위키에서는 수정하면 사라지지만 git은 그렇지 않습니다. 히스토리에 남고, 포크와 캐시에도 남습니다.

규모는 확인되어 있습니다. GitGuardian의 2026년 보고서 기준 공개 GitHub에서 발견된 유출 시크릿은 2,900만 건이고, AI 서비스 관련 키 유출은 전년 대비 81% 늘었습니다. 그리고 2025년 보고서의 수치가 더 뼈아픕니다.

2022년에 유출된 시크릿의 70%가 여전히 유효했습니다.

유출은 사건이 아니라 상태입니다.

이관 전에 시크릿 스캐닝을 pre-commit과 CI 양쪽에 걸고, 푸시 보호를 켜고, 이관 대상 문서를 일괄 스캔하는 것이 순서입니다. 이 셋이 없으면 이관을 시작하지 않는 것이 낫습니다.

그래서 무엇을 어디로 옮길까요

앞의 세 가지 통제가 갖춰졌다는 전제에서, 우선순위는 다음과 같습니다.

현재 형태	옮길 형태	왜	분류 주의
이미지로 붙은 아키텍처	Mermaid, PlantUML 소스	diff·검색·리뷰 가능	내부 IP·호스트명 제거
위키의 배포 절차	저장소 내 런북 + 스크립트	문서와 실행이 같은 곳에	자격증명 경로 분리
메신저에 흩어진 결정	ADR	"왜"는 AI가 가장 추론하지 못하는 정보	대체로 낮음
스프레드시트 서비스 목록	YAML 서비스 카탈로그	스키마 검증, CI 연동	토폴로지 노출 검토
구전되는 코딩 규칙	린터 규칙 + `AGENTS.md`	강제 가능, 자동 검출	`CODEOWNERS` 보호 필수
위협 모델	이관 보류 또는 별도 통제 저장소	편익보다 노출 위험이 큼	최고 등급

이 중 가장 저평가된 것이 ADR입니다. 모델은 코드를 읽고 "무엇을 하는지"는 잘 복원합니다. 그러나 "왜 이 방식이 아니라 저 방식을 골랐는지", "어떤 대안을 검토하고 왜 버렸는지"는 코드 어디에도 없습니다.

이 정보가 없으면 에이전트는 팀이 3년 전에 이미 폐기한 설계를 자신 있게 다시 제안합니다. 그리고 ADR은 분류 등급이 대체로 낮아서 위험 대비 효과가 가장 좋습니다. 시작점으로 삼기에 적절합니다.

옮길 때의 원칙은 단순합니다. 단일 원본은 저장소에 두고, 파일 하나에 주제 하나를 담고, 깨진 링크나 시크릿 같은 검증은 CI에 맡기는 것입니다.

결론

AI를 잘 쓰기 위해 조직이 갖춰야 할 것은 대체로 새 모델이 아닙니다. 이미 갖고 있는 지식을 AI가 이해할 수 있는 형태로 옮겨서, 지식이 만들어지는 속도와 꺼내 쓰는 속도를 일의 속도에 맞추는 작업입니다. 코드베이스는 이 일을 20년에 걸쳐 이미 해냈고, 남은 것은 코드 바깥의 자산에 같은 규율을 적용하는 것입니다.

다만 그 규율에는 보안이 포함되어야 합니다. 문서를 저장소로 옮기는 순간 그 문서는 에이전트를 조종할 수 있는 통로가 되고, 읽기 권한은 저장소 단위로만 걸 수 있게 되고, 실수는 히스토리에 영구히 남습니다. 이 세 가지를 처리하지 않은 이관은 검색성을 얻는 대신 통제를 잃는 선택이 됩니다.

형상 관리의 무게 중심이 "사람이 보기 좋은 것"에서 "AI가 이해하기 좋은 것"으로 옮겨가고 있는 것은 맞습니다. 그리고 그 둘은 생각보다 자주 같은 방향을 가리킵니다. 검색되고, 리뷰되고, 버전 관리되고, 분류된 문서는 애초에 사람에게도 더 좋은 문서였습니다.

다만 이 변화는 새로운 공격 표면을 함께 만듭니다. 그에 대한 대비를 먼저 갖춘 뒤에 옮겨가는 것이 올바른 순서라고 생각합니다.

긴 글 읽어주셔서 감사합니다.