요즘 나는 문서를 어디에 둬야 할지 자꾸 흔들린다 (AI랑 같이 일하는 시대, MD vs Docs/Confluence)

요즘 내가 계속 붙잡고 있는 질문

요즘은 글을 쓰다가도, 문서를 만들다가도, 결국 마지막에 같은 질문으로 돌아온다.

“이걸 어디에 남기지?”

Google Docs에 쓰자니, 나중에 AI에게 다시 컨텍스트로 먹이기 애매한 순간이 있고,
Confluence에 올리자니 유통은 되는데 “결정의 원본”을 거기에 둬도 되나 싶다.
그러다 결국 로컬 폴더의 .md 파일로 돌아오고, 또다시 “근데 이게 팀에 퍼지나?”를 걱정한다.

그러니까 요즘 내 고민은 문서 정리 방식 그 자체라기보다, 문서를 어디에 어떻게 남길지가 하루에도 몇 번씩 마음을 흔든다는 쪽에 가깝다.

AI와 같이 일하는 시간이 늘수록 이상한 감각이 생긴다.
내가 쓰는 문서가 사람에게만 읽히는 게 아니라, AI에게도 ‘컨텍스트’로 들어가야 하는데… 그 관문을 통과하는 문서와 아닌 문서가 너무 명확하게 갈린다.

그래서 자연스럽게 이런 질문이 떠올랐다.

• Google Docs나 Confluence 같은 전통적인 문서화 도구보다
• 그냥 Markdown(MD) 파일로 글을 관리하는 게 더 낫지 않나?

그리고 나는 한동안 이 질문을 거의 “정답 찾기”처럼 붙잡고 있었다.
하지만 요즘은 조금 결이 바뀌었다. “무조건 MD가 답” 같은 결론을 내리면, 오히려 문서화 자체가 무너지는 순간이 있다는 걸 여러 번 겪었기 때문이다.

---

내가 느낀 변화: 문서가 ‘사람만’ 위한 게 아니게 됐다

예전엔 문서의 목적이 대체로 “사람이 읽고 합의하기”였다.
그런데 지금은 문서가 다음 역할까지 맡는다.

• AI에게 프로젝트의 규칙/의도/제약을 먹이는 컨텍스트
• AI가 요약·추출·검증·갱신하는 자동화 파이프라인의 입력
• 팀의 기억(why/decision)을 남겨 미래의 나/동료/AI가 재사용하는 저장소

이렇게 문서의 “독자”가 사람에서 AI까지 확장되면, 문서가 갖춰야 하는 조건이 생긴다.
텍스트로 깔끔하고, diff가 가능하고, 링크 구조가 단순할수록 AI와 자동화에 유리해 보인다(내 체감상).

그래서인지 나는 최근 들어 “MD로 남기면 마음이 편하다”는 순간이 많아졌다.

---

MD가 계속 손에 잡히는 이유(내가 체감한 장점들)

MD를 “그냥 가벼운 글 포맷”으로만 보면 과소평가하게 된다.
MD를 Git 기반 운영(리뷰/이력/자동화)까지 포함해서 보면, 내 입장에선 강점이 더 또렷하게 느껴진다.

1) 변경이력과 리뷰가 ‘기본값’이 된다

문서도 코드처럼 PR로 바뀐다.
즉, “문서 변경도 검토/승인된 변경”으로 남는다. 이게 생각보다 마음이 편하다.

• ADR(의사결정 기록)
• API 스펙
• 런북/온콜 문서
• 운영 정책(배포/롤백/장애 대응)

이런 문서들은 (내가 일할 때는) 사실상 제품의 일부처럼 취급되는 경우가 많아서, 리뷰 가능한 변경 이력이 큰 자산처럼 느껴진다.

2) 자동화(문서 CI)가 붙기 쉽다

• 링크 깨짐 검사
• 문서 린트(템플릿/섹션/필수 항목)
• 코드 예제 실행/검증
• 스펙 변경 시 영향 범위 체크

“문서도 제품 품질의 일부”라고 보면, MD+CI 조합이 꽤 매력적으로 보인다.

3) AI 컨텍스트로 쓰기 쉬운 형태다

MD는 기본적으로 plain text라서:

• AI에게 넣기 쉽고
• 검색/전처리/임베딩 파이프라인 만들기도 쉽고
• 벤더 락인이 약하다(이사/백업/마이그레이션이 수월)

요즘 내가 특히 크게 느끼는 건 “나중에 내가 다시 읽어도 좋다”는 점이다.
기계가 읽기 쉬운 건, 사람이 다시 읽기 쉬운 경우가 많다. (적어도 내 경험상.)

---

그런데도 Docs/Confluence를 버리기 어려운 이유

Docs/Confluence류가 강한 이유도, 써보면 꽤 분명하게 느껴진다.
이건 “구식 도구라서”가 아니라 사람 협업이 정말 편하게 되도록 잘 만들어져 있기 때문에 가깝다.

1) 사람 협업(합의)이 빠르다

• 코멘트/제안 모드
• 실시간 공동 편집
• 공유/권한 설정
• 템플릿, 조직 내 배포/노출

문서의 목적이 “토론→합의→정렬”일 때는, 내 체감상 이쪽이 마찰이 훨씬 낮다.

2) 비개발자 비중이 높을수록 이점이 커진다

디자인/PM/영업/CS/법무 등 다양한 직군이 참여하는 문서는
MD+Git이 오히려 “진입 장벽”이 된다.

그러니까 결국 독자(누가 읽고 누가 편집하는가)가 중요하다는 생각으로 돌아오게 된다.

3) 거버넌스/보안/감사에서 기본 옵션이 많다

조직 정책에 따라 다르지만 대체로:

• 권한/공유/보존
• 감사 로그
• 조직 내 검색/분류

이런 “문서 운영의 관리 비용”을 낮춰주는 느낌이 있다.

---

결정타는 이것: “AI가 그 문서를 실제로 읽을 수 있나?”

여기서 한 번 멈춰서 생각하게 된다.
회사 문서(특히 Docs/Confluence)는 인증/권한 때문에 AI가 자동으로 읽기 어려운 경우가 꽤 있다(적어도 내가 겪은 환경에서는).

• 링크는 있는데, AI가 접근하면 로그인 벽
• 권한이 부서/그룹 단위로 복잡
• 외부 툴이 API로 접근하기 까다로운 구성

그래서 “AI가 요약/추출/갱신까지 해주는 문서”를 꿈꾸면, 결국 접근성(권한/인증) + 구조화(텍스트화)가 병목이 된다.
MD는 이 문제에서 기본값으로 유리해 보이는 편이다.

이 부분을 깨닫고 나서는 “MD가 더 좋다”가 아니라, “AI와 같이 굴려야 하는 문서는 접근성이 생명일지도” 쪽으로 생각이 정리됐다.

---

내가 요즘 정리해보는 방향: ‘도구 선택’이 아니라 ‘SSOT 설계’다

그래서 요즘은 이 고민을 “MD vs Docs” 전쟁으로 보지 않으려고 한다.
대신 문서 타입별로 “진짜 원본(SSOT)”을 어디에 둘지부터 정한다.

내가 가장 자주 떠올리는 판단 기준은 아래 3가지다(아직은 개인 기준).

1) 독자 기준: 누가 쓰고 읽나?

• 개발자/AI 에이전트 비중이 높다 → MD가 기본값이 되기 쉬운 것 같다
• 비개발자 비중이 높다 → Docs/Confluence가 기본값이 되기 쉬운 것 같다

2) 변경 흐름 기준: 무엇과 함께 바뀌나?

• 코드/배포와 같이 바뀐다 → MD(+repo)가 더 잘 맞는 경우가 많아 보인다
• 합의/커뮤니케이션이 중심이다 → Docs/Confluence가 더 편한 경우가 많아 보인다

3) 운영 기준: 거버넌스/감사/보안 비용은 누가 지불하나?

• Docs/Confluence: 기본 제공이 많아 운영 부담이 낮을 수 있음
• MD: Git으로 구현 가능하지만 세팅/문화/운영 비용이 올라갈 수 있음(이 비용을 내가/팀이 감당할 의지가 있는지)

---

운영 패턴: 지금은 하이브리드가 가장 그럴듯해 보인다

패턴 A) “초안/합의는 Docs, 확정/SSOT는 MD”

1. Docs에서 RFC/제안서/회의록을 빠르게 작성하고 코멘트로 합의한다
2. 결정이 나면 MD(ADR/스펙/런북)로 옮긴 뒤 PR로 승인한다
3. 최종 원본은 MD에 두고, Docs에는 링크와 요약만 남긴다

내가 이 패턴을 좋아하는 이유는 간단하다.
Docs는 “결정을 빠르게 만들기”에 더 잘 맞고, MD는 “결정을 오래 유지하기”에 더 잘 맞는 것 같다고 느낀다.

패턴 B) “SSOT는 MD, Docs/Confluence는 유통 포털”

• 원문은 리포지토리(또는 개인 지식 베이스)의 MD로 유지
• 읽기 경험은 문서 사이트 등 렌더링으로 제공
• Confluence에는 “요약 + 링크”로 조직 내 검색/노출을 활용

---

그래서 내 직감은 맞는가(“AI 시대니까 MD가 더 낫지 않나?”)

“AI/개발 워크플로에 붙는 문서” 영역에서는, 그 직감이 꽤 맞는 것 같기도 하다.

• 컨텍스트 재사용
• 리뷰 가능한 변경 이력
• 자동화/검증 가능성

다만 “조직 합의/커뮤니케이션”까지 전부 MD로 몰아버리면(혹은 몰아버리고 싶어지면),

• 협업 비용이 올라가고
• 문서가 안 읽히고
• 결국 문서화 자체가 삐걱거릴 가능성이 커진다(내가 겪은 몇 번의 실패처럼)

그래서 나는 아직 결론을 내리기보다는, 아래를 가설로 두고 있다.

AI 시대에 문서 운영을 잘 하려면 “MD로 통일”이 아니라
문서 타입별로 SSOT를 다르게 두는 하이브리드 설계가, 적어도 내 상황에선 실패 확률을 낮춰줄 가능성이 크다.

그리고 이게 정말 맞는지 확인하려면, 결국 “내가 실제로 그렇게 운영해보고” 체감 비용을 따져봐야 한다.

---

(내가 해보려는) 작은 실험: 문서 분류부터 시작하기

나는 당장 모든 문서를 바꾸기보다, 아래처럼 “문서 타입”을 먼저 나눠보려 한다.

• MD SSOT 후보: ADR / 스펙 / 런북 / 운영정책 / 온콜 / 체크리스트
• Docs SSOT 후보: 회의록 / 제안서 초안 / 합의용 원페이저 / 대외 공유용 문서
• 포털(요약+링크): Confluence(또는 사내 위키)에 핵심 문서 링크 허브 만들기

이걸로 “문서가 AI와 함께 굴러가게 만드는 기반”이 잡힐지, 아니면 다른 병목(예: 유통/검색/정렬)이 터질지부터 확인해보려 한다.

---

마무리

문서 도구 선택은 취향 문제가 아니라, 팀의 의사결정 방식과 운영 비용을 어디에 지불할지의 문제라고 생각한다.
나는 요즘 “AI와 협업” 때문에 MD 쪽으로 무게가 실리는 건 자연스러운 흐름이라고 느끼면서도, Docs/Confluence가 담당하는 “합의와 유통”의 가치를 무시하면 문서화가 실패할 수 있다는 감각도 같이 들고 있다.

그래서 이 글은 “정답”을 주장하려고 쓰는 게 아니라,
내가 어떤 가설을 세웠고, 어떤 방식으로 실험해보려 하는지를 기록해두려는 목적이 더 크다.