“무거운 비유는 조심한다.
다만 조직 안에서 문서가 하는 일에는, 가끔 같은 문법이 반복된다.”

먼저 선을 긋고 싶다.

이 글은 역사책식 단정이나, 실명 조직을 들먹이며 싸우는 글이 아니다. 합성 사례와 일반화다.

요즘 여러 회사에서 비슷한 일이 겹친다고 느낀다.
에이전트와 템플릿이 문서 초안을 잘 써 주니, docs/·Notion·ADR이 빠르게 두꺼워진다. 동시에 SSOT·거버넌스·워크스트림 같은 말이 운영의 중심으로 올라온다. 농담 한 마디로 끝낼 크기가 아니다.

다만 나는 우리 쪽 docs/ 같은 곳을 정리할수록, 익숙한 불안이 든다.

그 불안을 스스로에게 솔직히 이름 붙이면 이렇게 가깝다.

  • 하나의 진실(SSOT) 이 너무 달콤할 때
  • 전장을 담는 지도가 너무 커질 때
  • 죄목 번호가 붙은 안티패턴이 사람을 대신 말할 때
  • 거버넌스 표가 분기마다 눈을 들여다볼 때
  • 하네스(Harness) 가 안전이 아니라 입맞추기로 들릴 때

아래는 실제로 본 문서 구조를 바탕으로 한 합성 사례다.
회사명·레포명·티켓·URL·내부 도구 이름은 의도적으로 바꿨다.
그래도 “이거 우리 팀 같다”는 느낌이 들게 하려고, 형태는 최대한 구체적으로 남겼다.

공개 제목을 이렇게 고른 이유

이 글이 말하는 건 플랫폼·문서·거버넌스 설계가 사람에게 어떻게 읽히는지다.
그런데 제목이 과하면, 독자는 본문보다 먼저 감정을 쓴다. “겨우 문서 맞추라는 걸 그렇게까지 말하나”라며 읽기 전에 화가 나거나, 논지와 무관한 쪽으로 튕겨 나가기 쉽다. 메신저를 치기도 쉽다.

그래서 공개 제목은 무엇이 불편한지가 바로 드러나는 쪽으로 고정했다. 같은 줄기의 다른 후보는 이런 것들이었다.

  • 거버넌스의 그림자
  • SSOT가 합법성이 되는 순간 (채택)
  • 플랫폼 엔지니어링이 관료주의가 될 때

아래 본론은 중심주의가 문서와 도구에 새겨질 때의 문법만 다룬다. 자극적인 레이블은 붙이지 않겠다.

내가 말하는 조직적 중심주의의 좁은 정의

여기서 내가 쓰는 말은 조직적 중심주의(centralism) 로 정리한다.

  • 세계를 한 표로 정렬하고 싶은 욕망
  • 예외를 승격 경로 같은 관문으로 통제하고 싶은 욕망
  • 사람의 판단을 번호 붙은 규범으로 대체하고 싶은 욕망
  • “지금 안 하면 위험하다”는 긴급 서사로 시간을 모으고 싶은 욕망

이건 악의가 없어도 생긴다.
오히려 성실한 플랫폼 엔지니어가 가장 잘 만든다.

그래서 위험하다.

사례 A — “문서가 SSOT다”는 선언과 다섯 계명

합성 설정: 한 이커머스 조직의 프론트엔드 모노레포. 루트에 docs/가 있고, README 첫머리에 이런 문장이 있다.

이 디렉터리는 명세·가이드·아키텍처·워크스트림의 SSOT다.

표로 어디에 무엇이 있는지를 정리하고, 다섯 가지 원칙을 적는다.
예를 들면 이런 종류다.

  1. 중복 금지
  2. 포인터 우선
  3. 요약만 직접 기술
  4. 코드 변경 시 문서 동기화
  5. 임시 메모와 분리

그다음 표가 하나 더 나온다. “상황 → 승격 경로” 다.

  • 단일 PR로 끝나면 승격 없음
  • 횡단 사실을 발견하면 specs/
  • 절차가 생기면 codeGuides/
  • 큰 작업이면 workstreams/
  • 안티/굿 패턴이면 architecture/ …

왜 이게 중심주의의 그림자인가

표면적으로는 건강한 운영이다.
문제는 이 구조가 쉽게 이렇게 읽힐 때다.

“공식 기록에 안 올라온 생각은, 존재하지 않는다.”

승격 표는 관문이다. 관문은 좋다.
다만 관문이 많아질수록, 사람은 먼저 문서를 쓰는 쪽으로 기울고, 먼저 코드를 고치는 쪽으로 기울기 어려워진다.

그 순간 SSOT는 “진실의 원천”이 아니라 합법성의 원천이 된다.

사례 B — 마스터플랜: “One Way”와 “Zero”

합성 설정: 아키텍처 최적화를 위한 장문의 계획서. Executive Summary가 영어로 쓰이고, 위험은 이모지(🚨)로 강조된다.

핵심 구호는 이런 쪽이다.

  • Unify — “한 가지 방법”
  • Modernize — 레거시 제거
  • Optimize — 네트워크·초기화·DX

표에는 우선순위가 매겨진다.
그리고 성공 상태는 종종 이렇게 적힌다.

  • 어떤 폴더는 0이 되어야 한다
  • 어떤 라이브러리는 0이 되어야 한다
  • 어떤 클래스의 런타임 오류는 0이 되어야 한다

왜 이게 중심주의의 그림자인가

“하나의 길”은 기술적으로 종종 맞다.
다만 Zero 타깃은 몫과 지위의 언어로도 읽힌다.

“남아 있는 것은 다 부끄러운 잔재다.”

이 문법이 강해지면, 팀은 정화(cleanup) 를 정책의 중심에 두게 된다.
정화는 필요하다.
그런데 정화가 유일한 도덕이 되면, 제품의 예외·현장에서만 통하는 타협·운영의 미세한 줄다리기가 설 자리가 줄어든다.

사례 C — 전장 지도: 페이지 인벤토리와 API 맵

합성 설정: “페이지 URL 목록” 문서가 수백 줄을 넘어간다.
코드 스캔에 더해, 에러 트래킹·APM까지 끌어와 트래픽 표기를 단다.

Executive Summary에는 조사 범위·방법·앱 개수·basePath 표가 들어간다.
문서 상단에는 “다음 정기 보강 시점” 같은 유지보수 약속이 붙는다.

왜 이게 중심주의의 그림자인가

이건 관측이다. 관측은 권력의 기본 재료다.

지도가 커질수록, 사람은 지도 밖을 다니기 어려워진다.
“인덱스에 없는 라우트”는 실수처럼 보이기 쉽다.
그런데 실제 제품은 인덱스보다 먼저 움직이는 경우가 많다.

여기서 위험한 건 지도 자체가 아니라,
지도가 정당성의 기준으로 승격되는 순간이다.

사례 D — 안티패턴 감사: 번호 붙은 죄목과 표본 전시

합성 설정: “안티패턴 레포트”가 있다. 목차는 AP-1 … AP-10처럼 번호가 박혀 있다.

각 항목은 정의 → 발견 사례 표 → 심각도로 간다.
표에는 파일명 대신 줄 수, 훅 개수, 혼재 책임 수가 들어간다.

왜 이게 중심주의의 그림자인가

기술 부채를 법전으로 바꾸면, 리뷰가 이렇게 짧아진다.

“AP-3 위반입니다.”

이건 빠르다. 빠른 것은 좋다.
다만 사람의 설명이 빠지면, 죄목은 쉽게 인격 대체가 된다.

나는 안티패턴 문서가 없어야 한다고 보지 않는다.
다만 그 문서가 재판 기록처럼 쓰이기 시작하면, 팀은 학습보다 면죄부를 먼저 찾는다.

사례 E — 에이전트 하네스(Harness): 일관성, Long Memory, 협업 인식

용어부터: 여기서 하네스(Harness) 는 “말(에이전트)에 채우는 고삐” 같은 비유다. 팀이 정한 규칙·플러그인·금지선을 묶어, 여러 레포에서 AI가 비슷한 행동을 하게 만드는 설계를 가리키는 말로 쓰인다. 주니어 입장에선 생소할 수 있어, 한 줄로만 짚고 간다.

합성 설정: “팀 공통 AI 도구와 Long Memory”를 다루는 상위 설계 문서가 있다.

목표는 이런 종류로 읽힌다.

  1. 어떤 레포/작업자에서든 동일한 팀 컨텍스트
  2. 공통 도구의 한 곳 관리·전 레포 배포
  3. 세션을 넘는 Long Memory 축적
  4. Draft PR 기반으로 에이전트가 작업 현황을 인식 …

아키텍처 다이어그램에는 Personal + Team Plugin + Repo 같은 층이 있다.

왜 이게 중심주의의 그림자인가

이건 나쁜 설계가 아니다. 오히려 안전과 비용 절감에 가깝다.

그런데 문장이 이렇게 들릴 때가 문제다.

“개인의 맥락은 위험하니, 팀이 정의한 맥락으로 덮자.”

Long Memory는 지식이기도 하고 감시 가능한 기록이기도 하다.
Draft PR 인식은 협조이기도 하고 가시성 강요이기도 한다.

특히 Draft PR 은 원래 “아직 말하지 않은 시도”를 남기는 공간인 경우가 많다. 거기에 에이전트나 팀 도구가 현황판처럼 붙으면, 설명할 준비가 되기 전에 내 브랜치가 팀의 시야에 올라온다. 주니어에게는 이게 곧바로 실수 비용으로 번역되기 쉽다. 그래서 같은 기능도 “일을 편하게 맞춰 준다”가 아니라 먼저 입을 맞추게 한다로 들릴 수 있다.

여기서 중요한 건 기술 선택이 아니라 동의의 언어다.
“왜 이렇게 보이게 하지?”가 먼저 오면, 같은 도구도 다르게 느껴진다.

사례 F — 거버넌스: 분기 리뷰와 CI의 경로 금지

합성 설정: 문서 루트 README에 거버넌스 절이 있다.

  • 분기별로 워크스트림 상태 표를 리뷰한다
  • PR에서 코드와 문서 모순을 잡는다
  • (계획된) CI는 특정 경로가 diff에 나오면 실패한다
  • 사내 툴킷으로 문서 상태 조회·워크스트림 생성·문서 린트 같은 작업을 슬래시 커맨드 형태로 표준화한다

왜 이게 중심주의의 그림자인가

자동화는 하한선을 만든다. 하한선은 필요하다.

다만 CI가 “이 경로 금지”로 읽히기 시작하면, 개발자는 이렇게 행동한다.

“걸리지 않게 PR을 쪼개자.”

이건 나쁜가? 상황에 따라 다르다.
나쁜 신호는 이것이다: 의도가 설명되지 않은 채 실패가 누적될 때.

실패가 교육이 아니라 처벌로 들리면, 문서는 SSOT가 아니라 순응 테스트가 된다.

그럼에도 나는 이 문서들을 없애고 싶지 않다

중요한 반전이다.

위 사례들은 “나쁜 팀”의 증거가 아니다.
오히려 성과를 내는 팀이 더 자주 만든다.

내가 겁내는 건 문서의 존재가 아니라, 문서가 이렇게 교체될 때다.

빠져야 할 것 문서가 대신할 때 생기는 일
정치(자원 배분) “문서에 없으면 못 한다”
대화(합의) “표에 없으면 없는 일”
책임(소유) “AP 번호로 끝”
시간(리팩터 예산) “마스터플랜이 있으니 곧”

여기서 정치는 사내 정치(뒤에서 밀고 당기기)를 뜻하지 않는다.
누가 무엇에 시간을 쓸지, 무엇을 나중으로 미룰지를 두고 벌이는 공개된 다툼·타협·우선순위 조율—즉, 민주적이든 관료적이든 자원을 배분하는 과정을 말한다. 그 과정이 얇아지면 문서가 그 빈자리를 메우기 쉽다.

조금 더 실제적으로: 내가 팀에 걸고 싶은 안전장치

합성이 아니라, 원칙만 적는다.

  1. SSOT는 ‘진실’이 아니라 ‘출입구’로 읽히게 쓴다. 진실은 PR과 테스트와 로그에 더 가깝게 둔다.
  2. Zero 타깃 옆에 항상 예외의 정당성을 적는다. “왜 아직 남았는가”를 부끄러움이 아니라 정보로 둔다.
  3. 안티패턴 번호는 토론의 끝이 아니라 시작점으로 쓴다. “AP-3” 다음에 한 문장의 맥락을 요구한다.
  4. 하네스는 “통일”보다 금지선·로그·복구를 먼저 문서화한다.
  5. 지도(인벤토리) 는 최신이 아니어도 된다고 명시한다. 지도는 항상 늦는다. 늦음을 전제로 운영한다.

마치며

docs/ 같은 팀 공유 문서는, 내가 일하는 방식을 구원해 주기도 하고,
동시에 나를 순응시키는 언어로 변하기도 한다.

그 긴장을 자극적인 한 마디로 포장하는 건 과장이고, 오해를 부른다.
그래도 그 긴장을 가볍게 흘리면, 나는 너무 편안해져서 위험을 늦게 본다.

한 줄 결: 문서 중심주의의 끝은 진리가 아니라 합법성이고, 합법성의 끝은 사람이 말할 수 있는 정치를 문서가 대신하는 순간이다. 나는 그 순간만큼은 피하고 싶다.