AI를 활용하는데 어떤 형식의 문서가 좋을까? (생각 직접 작성 후 AI 활용)

AGENTS.md 파일은 핵심 컨텍스트를 AI Agent에게 부여하는 역할을 해요.
개발자들은 행동 규칙, 코드 스타일, 프로젝트 구조 같은 핵심 정보들을 AI Agent가 쉽게 읽도록 만들어요.

AI 활용이 본격적으로 시작되는 초기에는(초기라고 하기엔 1~2년 정도 된 것 같지만) AGENTS.md 파일 1개에 기본 프롬프트를 때려박는 느낌으로 만들었어요. 이 프롬프트에 따라 결과가 천차만별로 달라졌어요. 그래서 사람들은 컨텍스트 엔지니어링 기법들을 활용해 더 좋은 결과를 얻고자 노력했어요.

하지만 곧 문제들이 드러났어요.

LLM 모델의 Context 허용량 문제
너무 긴 프롬프트로 인한 토큰 낭비
Context를 꽉 채웠을 때 오히려 결과 품질이 떨어지는 현상
프로젝트가 커질수록 관리가 어려워지는 문제

그래서 사람들은 SKILL, COMMAND 같은 개념들을 만들기 시작했어요.
필요할 때만 필요한 컨텍스트를 주입하도록 구조를 분리하기 시작한 거에요.

예를 들어:

코드 리뷰용 컨텍스트
테스트 생성용 컨텍스트
리팩토링용 컨텍스트
문서 생성용 컨텍스트

를 각각 따로 관리하는 방식이 등장했어요.

마치 소프트웨어 엔지니어링에서:

추상화
관심사 분리
모듈화

를 하듯이, AI 활용에서도 비슷한 흐름이 나타난 거에요. (역시 엔지니어 개발자들이야 !!)

그리고 이 흐름은 자연스럽게 Agent 개념으로 이어졌어요.

하나의 거대한 프롬프트 대신:

역할이 분리된 여러 Agent
특정 작업에 특화된 Agent
서로 협업하는 Multi-Agent 구조

를 활용하기 시작했어요.

Agent Harness의 등장

여기서 한 단계 더 발전한 개념인 Agent Harness까지 등장했어요. ( Opencode 블로그 글에 이미 소개했어요)

이제는 사람이 직접 Agent를 하나씩 실행시키는 게 아니라:

여러 Agent를 자동으로 orchestration 하고
병렬 처리하고
작업을 분배하고
결과를 조합하는

구조들이 만들어지고 있어요.

즉 AI 활용 방식이 점점:

Prompt→ Skill→ Agent→ Agent Harness

형태로 고도화되고 있는 거에요.

품질과 생산성은 엄청나게 좋아졌어요.

하지만 동시에 새로운 문제가 생겼어요.

AI를 활용하면 문서 생산량이 폭발적으로 증가해요.

예를 들어:

요구사항 정리
기획 문서
API 명세

같은 것들이 거의 자동 생성되기 시작했어요.

문제는 여기서부터였어요.

AI는 문서를 정말 잘 만들어요.
문제는 사람이 그걸 다 읽지 못한다는 거에요.

저는 Confluence, Notion, Google Drive 같은 문서 플랫폼들에 AI를 연결해서:

문서 작성
문서 관리
자동 요약
개발 자동화

같은 것들을 실제로 많이 해봤어요.

그런데 느낀 점은 하나였어요.

AI 성능이 좋아질수록
사람은 문서를 더 안 읽게 된다.

문서 양과 퀄리티는 계속 좋아지는데,
사람은 그걸 다 검증할 수 없으니 다시 AI로 요약시키게 돼요.

"AI 생성 비용 < 인간 검증 비용"이 되는 순간이 와버린 거에요.

저는 이 문제를 어떻게 해결할 수 있을까 고민하게 되었어요.

AI에게 좋은 문서와 사람에게 좋은 문서는 다르다

요즘 커뮤니티나 유튜브를 보면 크게 두 파로 나뉘어요.

Markdown(.md)이 좋아
HTML이 좋아

전자의 경우에는 AI가 읽고 이해하기 가장 효율적인 형태로 보기 때문이고, 후자의 경우엔 .md가 사람이 읽기 힘들기 때문에 사람이 더 읽기 쉽게 만들 수 있는 html이 좋다고 하는 것이에요.

한번 그 예를 사진으로 보여줄게요

1 / 2

사진처럼 md 파일은 좌우 공간 활용이 힘들기도 하고, 시각적으로 공간 활용하기가 더 힘들어 보여요. 하지만 형식에 맞춰 작성하기 때문에 훨씬 AI 친화적일 거에요. 하지만 html은 ui가 매우 자유로워요. 그래서 사람에게 시각적으로 깔끔하게 보일 수 있고, 정보 밀도 조절도 좋아요.

이제 .md파와 .html파의 주장, 장단점들을 파악해봐요.

Markdown(.md) 문서파

Markdown 진영은 기본적으로:

“AI가 읽기 좋은 문서를 만들자”

라는 철학에 가까워요.

실제로 Markdown은 AI가 읽기 정말 좋은 형식이에요.

왜냐하면:

구조가 단순하고
계층이 명확하고
의미 구조가 텍스트에 직접 드러나기 때문이에요.

예를 들어:

# 프로젝트 구조## 인증- JWT 사용- Redis Session 사용## 코드 스타일- any 금지- eslint strict mode

이런 구조는 AI가 이해하기 굉장히 쉬워요.

특히 LLM은:

#
##
리스트
코드 블록

같은 구조를 통해 중요도와 계층을 추론해요.

=> 계층을 통한 가중치 계산 적용(attention 전달) => Lost in the Middle, Primary / Recency Bias 완화

그래서 Markdown은 단순 문서라기보다:

“AI 친화적 구조화 텍스트”

에 가까워요.

그리고 실제로도:

Git diff 관리 용이
버전 관리 편리
토큰 효율 좋음
parsing 안정적

같은 장점들이 있어요.

HTML(.html) 문서파

문서가 작을 땐 Markdown도 충분히 좋아요. 하지만 프로젝트 규모가 커지면 이야기가 달라져요.

예를 들어:

수백 페이지 요구사항
복잡한 상태 흐름
멀티 Agent 구조
권한 체계
업무 프로세스
시스템 관계도

같은 것들을 Markdown만으로 표현하기 시작하면 한계가 금방 와요.

왜냐하면 사람은:

시각적 강조
레이아웃
색
인터랙션
공간 분리

를 통해 정보를 읽기 때문이에요.

즉 사람은 단순 텍스트보다:

시각적 정보 구조화(Visual Information Architecture)

를 훨씬 잘 읽어요.

이런 이유로 최근에는 HTML 기반 문서 흐름도 커지고 있어요.

HTML 진영의 철학은:

“사람이 검증 가능한 문서를 만들자”

에 가까워요.

HTML은 단순히 예쁘게 만드는 수준이 아니라:

정보 밀도 조절
인터랙션
시각적 계층화
복잡한 관계 표현

에 강해요.

예를 들면:

접을 수 있는 섹션
상태 흐름 시각화
Agent 관계도
위험 요소 강조
Task 진행률
자동 요약 카드
인터랙션 가능한 문서

같은 것들을 훨씬 자연스럽게 표현할 수 있어요.

특히 Agent Harness 시대에는:

AI가 생성하고
사람이 검증하고
다시 AI가 실행하는

루프가 계속 반복되기 때문에,

사람이 “빠르게 이해할 수 있는 문서”의 중요성이 엄청 커지고 있어요.

결국 중요한 것은 "누가 읽는가"

저는 .html파 와 .md파가 나눠지는게 의미 없어질 거라 생각해요. 결국 누가 읽는 문서냐에 따라 둘다 적절하게 쓰일거에요.

AI가 읽는 문서라면:

구조화
단순성
토큰 효율
semantic hierarchy

가 중요해요.

반대로 사람이 읽는 문서라면:

시각적 구조
빠른 스캔
강조
정보 압축
인터랙션

이 중요해져요.

즉 AI 시대 문서는 결국 AI Layer와 Human Layer 형태로 분리될거라고 생각해요.

결국 "원본" + "뷰"로 둘다 관리

저는 결국 AI Layer와 Human Layer로 분리되어 둘다 관리될거라 생각해요. 그리고 Human Layer가 별도로 관리되기 보다는, AI를 통해 .md를 View로 바꿔주는 형식을 정의하고 사람이 필요할때 만들어 보는 방향이 될거라고 생각해요. (매우매우 개인적인 생각)

마치 리액트가 State를 분리하고, UI를 분리했듯이, 결국 엔지니어링 관점으로 원본 내용과 뷰를 관리하게 되겠죠.

그래서 저가 생각한 흐름을 나타내면 아래와 같이 될거라고 생각해요.

결론

요즘 뉴스를 보면 해고했던 개발자들을 다시 뽑는 경우가 계속 일어나고 있어요. 그 이유는 어느 한사람이 모든 것을 넓은 범위를 처리하는 것에는 한계가 있고, 결국 사람간의 대화를 통해 현실세계에서 무엇을 해야할지 결정되기 때문이라고 생각해요. AI가 무엇인가 만들어 주는데, 뭘 하려고 만들고 있는지 알지도 못한다면 컨트롤할 수 없는 제품이 나올거라 생각해요.

AI를 활용해 주로 해결해야하는 것은 코드가 아니라 사람간의 의사소통과 사람이 읽을 수 있도록 문서화하여 빠르게 파악할 수 있도록 하는 것이 되는 날이 오고있어요. 개발자로서는 코드도 잘하고, AI도 상황에 맞게 잘 쓰고, 의사소통과 문서화 어려움도 AI를 통해 해결할 수 있는 역량을 계속 키워야겠습니다..! 화이팅