이 글은 2026년 6월 시점에서의 자신의 생각을 정리한 것입니다.

세상의 의견이나 다른 입장을 부정하고 싶은 것이 아니라, 어디까지나 지금의 나에게는 이렇게 보인다는 이야기로서 쓰고 있습니다.

AI 에이전트(AI Agent)나 개발 현장을 둘러싼 상황은 변화가 빠르기 때문에, 향후의 경험이나 환경에 따라 자신의 생각도 변해갈 것이라고 생각합니다.

최근 AI 에이전트를 사용하여 개발하는 과정에서, 문서(Document)의 역할이 조금 변하고 있다는 느낌이 들고 있습니다.

지금까지 문서는 어느 쪽인가 하면 '결과물'로서 간주되는 경우가 많았다고 생각합니다.

설계서를 만든다.

사양서(Specification)를 만든다.

README를 작성한다.

납품물로서 정리한다.

인수인계 자료로서 남긴다.

물론, 지금도 그러한 역할은 있습니다.

다만, AI 에이전트가 개발에 참여하게 되면, 문서는 단순히 인간이 읽는 결과물이 아니게 되어가는 것처럼 보입니다.

AI가 문서를 읽는다.

AI가 그 전제를 바탕으로 코드를 작성한다.

AI가 코드를 읽고, 다시 문서를 만든다.

인간이 그것을 확인하고, 다시 전제를 업데이트한다.

이렇게 되면, 문서는 한 번 만들고 끝나는 자료라기보다, AI와 인간이 동일한 전제로 개발을 계속하기 위한 환경의 일부에 가까워지는 것이 아닐까.

최근에는 그렇게 느끼고 있습니다.

지금까지의 개발에서는 설계서나 문서가 기본적으로 인간이 읽는 것이었습니다.

인간이 설계서를 작성한다.

인간이 설계서를 읽는다.

인간이 코드를 작성한다.

인간이 리뷰(Review)한다.

인간이 유지보수(Maintenance)한다.

물론, 툴(Tool)에 의한 자동 생성이나, 코드로부터의 문서 생성은 이전부터 있었습니다.

다만, 그럼에도 많은 경우 문서의 주요 독자는 인간이었다고 생각합니다.

고객에게 설명하기 위해.

팀 내에서 인식을 맞추기 위해.

나중에 합류한 사람이 이해하기 위해.

납품물로서 남기기 위해.

그런 의미에서 문서는 '인간에게 설명하기 위한 자료'라는 색채가 강했다고 생각합니다.

다만, 이 형태에는 흔히 발생하는 문제도 있습니다.

코드는 변한다.

사양(Specification)도 변한다.

운용도 변한다.

하지만 문서는 업데이트되지 않는다.

결과적으로 설계서와 구현이 어긋나게 된다.

이것은 상당히 흔히 있는 일이라고 생각합니다.

오래된 문서는 인간에게도 곤란합니다.

하지만 인간은 아직 "이 자료, 오래된 것 같네"라고 의심할 수 있습니다.

현장 사람에게 물어볼 수도 있습니다.

코드와 대조하여 위화감을 눈치챌 수도 있습니다.

AI 시대가 되면, 여기에 조금 다른 무서움이 나타날 것 같다는 느낌이 듭니다.

AI 에이전트를 사용하게 되면, 문서의 독자에 AI가 추가됩니다.

README를 읽는다.

설계 메모를 읽는다.

작업 규칙을 읽는다.

제약 사항을 읽는다.

테스트 절차를 읽는다.

판단 이력을 읽는다.

그리고 그 전제로 코드를 작성하거나, 수정하거나, 조사합니다.

이것은 상당히 편리합니다.

매번 프롬프트(Prompt)로 전부 설명하지 않아도, 문서에 전제가 남아 있다면 AI는 그것을 읽고 작업할 수 있습니다.

다만, 여기서 문제가 되는 것은 AI가 읽는 문서가 반드시 옳다는 보장이 없다는 점입니다.

만약 오래된 README가 남아 있다면.

만약 옛날의 설계 방침이 그대로 남아 있다면.

만약 지금은 사용하지 않는 제약이 적혀 있다면.

만약 이미 변경된 사양이 아직 남아 있다면.

AI는 그것을 전제로 읽어버릴지도 모릅니다.

인간이라면 "이거 정말 지금도 맞나요?"라고 확인할 상황에서도, AI는 주어진 정보를 상당히 자연스럽게 사용하여 작업해 버리는 경우가 있습니다.

즉, 오래된 문서는 단순히 읽기 힘든 자료가 아니게 됩니다.

AI에게 잘못된 전제를 전달해 버리는 것이 될 가능성이 있습니다.

이 부분이 AI 시대의 문서에서 상당히 무서운 지점이라고 생각합니다.

AI 시대의 문서에서 흥미로운 점은, 흐름이 일방통행이 아니게 될 것 같다는 점입니다.

지금까지는 어느 쪽인가 하면 이런 흐름이었습니다.

인간이 설계서를 작성한다
↓
인간이 설계서를 읽는다
...

물론, 실제로는 설계서를 업데이트하는 경우도 있습니다.

다만, 현장감으로는 코드의 변화에 문서가 따라가지 못하는 경우도 많았던 것 같습니다.

AI 시대에는 여기에 다른 흐름이 들어옵니다.

인간이 합의나 제약을 문서에 남긴다
↓
AI가 문서를 읽는다
...

즉, 설계서에서 코드로 진행하는 것뿐만이 아닙니다.

코드에서 설계 자료로 되돌아오는 것도 가능합니다.

그리고 거기서 다시 문서를 업데이트하고, 다음 작업에서 AI가 읽게 됩니다.

설계서에서 코드로. 코드에서 설계서로. 그리고 다시 설계서에서 코드로.

이러한 사이클이 발생하게 될지도 모릅니다.

이것은 상당히 큰 변화라고 생각합니다.

설계서는 구현 전에 한 번 만들고 끝나는 것이 아니게 됩니다.

코드 또한 설계서와 분리된 구현 결과물만이 아니게 됩니다.

양쪽이 서로 오가며 개발의 전제(Premise)를 만들어 갑니다.

그렇게 생각하면, 문서는 납품물이라기보다 개발 환경의 일부로 보입니다.

AI에게 문서를 읽게 한다면, 그 문서가 오래되었다는 점이 미치는 영향은 상당히 커집니다.

예를 들어, 문서에 다음과 같이 적혀 있다고 가정해 봅시다.

• 이 기능은 사용되지 않음
• 이 화면은 향후 삭제 예정
• 이 API는 임시 대응
• 이 디렉터리에는 신규 기능을 추가하지 않음
• 이 테이블은 참조 전용으로 취급

만약 이것이 최신 정보라면, AI에게는 상당히 좋은 전제가 됩니다.

하지만 만약 오래된 정보라면 어떨까요?

이미 그 기능이 사용되고 있다.

그 화면은 삭제 예정이 아니게 되었다.

임시 대응이 정식 사양이 되었다.

신규 기능을 추가하지 않는 방침이 바뀌었다.

참조 전용이 아니라 업데이트하도록 바뀌었다.

이런 상태에서 AI가 오래된 문서를 읽게 되면 상당히 위험합니다.

AI는 오래된 전제에 따라 자연스러운 수정을 해버릴지도 모릅니다.

게다가 그 수정은 겉보기에는 그럴싸할 수 있습니다.

따라서 오래된 문서는 "읽히지 않으니까 문제없다"라고 말하기 어려워집니다.

AI가 읽게 되면, 오래된 문서는 실제로 작업에 영향을 주게 됩니다.

이 점은 인간만이 읽던 시대보다 더 중요해질 것이라고 느낍니다.

그렇게 생각하면 문서도 코드와 똑같이 다루고 싶어집니다.

코드를 변경하면 리뷰합니다.

테스트합니다.

차이(Diff)를 확인합니다.

필요하다면 되돌립니다.

마찬가지로 AI에게 읽히는 문서도 어느 정도는 업데이트, 리뷰, 유지보수를 하고 싶어집니다.

예를 들어, 코드 변경과 함께 다음과 같은 것들을 확인할 필요가 생길지도 모릅니다.

이러한 운용이 조금씩 필요해질지도 모릅니다.

물론 매번 전부 깔끔하게 업데이트하는 것은 힘든 일입니다.

다만 AI에게 읽히는 전제로 사용한다면, 방치된 문서는 다루기가 어려워집니다.

인간을 위한 설명 자료라면 다소 오래되었더라도 "참고 정도로 봐주세요"라고 말할 수 있습니다.

하지만 AI에게 읽히는 경우에는 참고 정도의 의도였더라도 AI가 이를 전제로 사용해 버릴 수 있습니다.

그래서 AI에게 읽히는 문서에는 적어도 다음과 같은 정보가 필요해집니다.

• 언제 시점의 내용인가
• 어느 범위에 유효한가
• 무엇이 미확정인가
• 어디가 오래되었을 가능성이 있는가
• 어떤 정보를 우선해야 하는가

이것은 인간을 위한 문서와는 조금 다른 사고방식입니다.

그렇다고는 해도 문서를 인간만으로 완벽하게 유지보수하는 것은 힘듭니다.

코드가 바뀔 때마다 설계서도, README도, 판단 이력도 전부 인간이 고친다.

이것은 현실적으로 상당히 무거운 작업이라고 생각합니다.

그래서 AI에게 문서 업데이트도 도와달라고 하는 방식이 늘어나지 않을까 생각합니다.

예를 들어,

• 이번 코드 변경으로부터 README에 추가해야 할 내용을 뽑아내기
• 변경 내용을 바탕으로 설계 자료의 차이(Diff) 안을 만들기
• 사양 변경의 판단 이유를 decision-log 형식으로 정리하기
• 테스트 절차의 변경점을 정리하기
• 오래되었을 법한 문서를 지적하기

이러한 방식입니다.

물론 AI가 내놓은 문서 업데이트 안을 그대로 믿는 것은 무섭습니다.

특히 왜 그렇게 판단했는지, 누구와 합의했는지, 무엇을 범위 외(Out of scope)로 했는지는 인간이 확인할 필요가 있습니다.

다만 무엇이 바뀌었는지 정리하거나 업데이트 안을 만드는 부분은 AI가 상당히 도와줄 수 있을 것 같다는 느낌이 듭니다.

즉, 문서를 AI에게 읽히는 것뿐만 아니라, 문서를 업데이트하는 작업에도 AI가 들어오게 된다.

여기서도 설계서와 코드의 사이클이 돌기 시작합니다.

여기까지 생각하면 문서는 단순한 성과물이 아니라 개발 환경의 일부로 보입니다.

소스 코드.

테스트.

빌드 절차.

Lint 및 타입 체크.

CI.

README.

설계 메모.

제약 사항.

판단 이력.

AI에게 읽히는 규칙.

이것들이 조합되어 AI와 인간이 개발하는 환경을 만들어 갑니다.

그런 이미지입니다.

개발 환경 (Development Environment)이라고 하면, 에디터나 실행 환경, CI/CD, 테스트 환경 같은 것들을 떠올리기 쉽습니다.

하지만 AI 시대에는 문서 (Document) 또한 그 영역에 포함되지 않을까 생각합니다.

AI는 문서를 읽고 작업을 수행합니다.

인간도 문서를 읽고 판단합니다.

코드가 바뀌면 문서도 바뀝니다.

문서가 바뀌면 AI의 작업 전제도 바뀝니다.

그렇게 생각하면, 문서는 정적인 설명 자료가 아니라 개발을 움직이는 전제의 일부입니다.

문서는 AI와 인간이 동일한 전제 하에 작업하기 위한 공유 컨텍스트 (Shared Context)가 된다.

지금의 저에게는 그렇게 보입니다.

AI 시대의 문서는 결과물로서 한 번 만들고 끝나는 것이 아니게 될 것 같다는 느낌이 듭니다.

인간이 읽는다.

AI가 읽는다.

AI가 코드를 작성한다.

AI가 코드로부터 설계 자료를 역생성 (Reverse Generation)한다.

인간이 확인한다.

문서를 업데이트한다.

다시 AI가 읽는다.

이러한 사이클이 늘어난다면, 문서는 납품물이라기보다 개발 환경의 일부에 가까워질 것입니다.

그렇기에 오래된 문서를 방치하는 것의 의미도 달라집니다.

인간이 조금 헤매는 것에 그치지 않고, AI에게 오래된 전제를 전달하게 될지도 모릅니다.

한편으로는 문서 업데이트 자체도 AI의 도움을 받을 수 있게 됩니다.

인간이 합의나 판단의 배경을 남기면, AI가 코드나 자료의 차분 (Diff)을 정리합니다.

그리고 인간이 확인하여 다시 전제를 업데이트합니다.

그렇게 문서를 키워나가며 개발을 진행합니다.

앞으로는 그러한 형태가 조금씩 늘어날지도 모르겠습니다.

저도 아직 정리 중입니다.

다만, 지금의 저에게 AI 시대의 문서는 결과물이 아니라 개발 환경의 일부로 보이고 있습니다.