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

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

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

최근 AI 에이전트를 사용하여 개발하는 과정에서, 문서(Document)를 바라보는 관점이 조금 바뀌었습니다.

이전에는 문서라고 하면, 인간에게 설명하기 위한 것이라는 감각이 강했습니다.

프로젝트의 개요를 작성한다.

설계 방침을 작성한다.

기동 방법을 작성한다.

사양을 작성한다.

주의점을 작성한다.

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

다만, AI 에이전트에게 작업을 맡기게 되면서, 문서는 인간에게 설명하기 위한 것만이 아니게 된 것 같다는 느낌이 듭니다.

AI에게 전제(Premise)를 전달하기 위한 것.

AI가 작업할 때 읽는 컨텍스트 (Context).

AI의 출력을 확인하기 위한 단서.

그러한 역할이 조금씩 늘어나고 있는 것처럼 보입니다.

AI가 코드를 읽을 수 있다면, 문서가 필요 없어지는 것이 아니라 오히려 그 반대일지도 모릅니다.

AI에게 무엇을 읽히느냐가 개발의 안정감에 상당히 큰 영향을 미친다.

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

AI 에이전트는 코드를 상당히 잘 읽습니다.

파일 구성을 보거나, 처리 흐름을 쫓거나, 함수나 클래스의 역할을 정리할 수 있습니다.

기존 코드 조사를 부탁하면, 인간이 처음에 읽는 것보다 빠르게 전체상을 파악해 주기도 합니다.

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

다만, 코드를 읽을 수 있는 것과 프로젝트의 전제를 이해하고 있는 것은 조금 다릅니다.

코드에는 현재의 구현(Implementation)은 남아 있습니다.

하지만 다음과 같은 사항은 코드만으로는 알기 어렵습니다.

• 왜 이 설계로 했는가
• 어디를 변경해서는 안 되는가
• 어떤 사양은 고객이나 관계자와 합의되었는가
• 어떤 처리는 잠정 대응인가
• 어떤 제약을 받아들이고 있는가
• 무엇을 확인하면 완료인가
• 어디까지가 이번 작업 범위인가

이러한 정보가 없는 상태에서 AI에게 작업을 맡기면, AI는 상당히 열심히 추측합니다.

그리고 추측한 상태 그대로, 그럴듯한 수정을 해버리는 경우가 있습니다.

그것이 무서운 점입니다.

AI가 나쁘다기보다, 이쪽에서 전제를 전달하지 못하고 있다.

그런 상황이 있는 것 같다는 느낌이 듭니다.

인간 사이의 개발에서도 전제 공유는 중요했습니다.

다만, 인간의 경우에는 대화 속에서 보완할 수 있습니다.

"여기는 건드리지 마세요"

"그 사양은 이번에는 대상 외입니다"

"그 처리는 과거의 경위로 남아 있습니다"

"이 기능은 얼핏 불필요해 보이지만, 운용에서 사용하고 있습니다"

이러한 이야기를 회의나 채팅, 리뷰를 통해 보충할 수 있습니다.

하지만 AI에게 작업을 맡길 경우, 그 전제가 문서로 남아 있지 않으면 매번 프롬프트(Prompt)로 설명해야 합니다.

그것은 꽤 힘든 일입니다.

매번 설명을 잊어버리는 일도 있습니다.

설명의 입도(Granularity)도 흔들립니다.

지난번에는 전달했는데 이번에는 전달하지 않았다, 라는 일도 일어납니다.

그래서 AI에게 읽힐 전제로서 문서를 남겨두고 싶어집니다.

이것은 인간에게 친절한 설명 자료라기보다, **AI에게 작업 전제를 전달하기 위한 컨텍스트 (Context)**에 가깝습니다.

AI에게 "이 프로젝트에서는 이렇게 생각하세요"라고 전달하기 위한 토대입니다.

AI에게 전달하는 문서는 길면 좋은 것이 아니라고 생각합니다.

오히려 AI가 작업할 때 필요한 전제가 어디에 있는지 알 수 있는 것이 더 중요해 보입니다.

예를 들어, 다음과 같은 것입니다.

물론, 전부를 깔끔하게 준비하는 것은 힘듭니다.

처음부터 완벽한 문서 세트를 만들려고 하면, 그 자체로 무거워져 버립니다.

다만, AI에게 맡기는 작업이 늘어날수록,

• 이 프로젝트에서는 무엇을 중요하게 여기는가
• 어디는 건드려도 되는가
• 어디는 신중하게 다루어야 하는가
• 무엇을 확인하면 되는가
• 무엇을 멋대로 판단해서는 안 되는가

를 남겨두는 가치는 올라가는 것 같다는 느낌이 듭니다.

AI 에이전트는 상당히 친절하게 움직여 줍니다.

이쪽에서 모호하게 의뢰해도 나름대로 형태를 만들어 줍니다.

다만, 그것은 편리한 한편으로 무서운 점이기도 합니다.

전제가 부족해도 AI는 멈추지 않고 진행해 버리는 경우가 있습니다.

예를 들어,

• 기존 사양을 변경해서는 안 되는데, 자연스러운 개선이라며 변경해 버린다
• 이번 스코프 (Scope) 외의 기능까지 고쳐 버린다
• 잠정 대응으로 남겨두었던 처리를 불필요한 처리라며 삭제해 버린다
• 업무 용어를 일반적인 의미로 해석해 버린다
• 테스트가 없는 부분을 겉보기에 자연스럽다는 이유만으로 판단해 버린다

이런 일들이 일어날 것 같습니다.

AI는 주어진 정보 안에서 자연스럽게 보이는 방향으로 나아갑니다.

그렇기에 자연스럽게 보이지만 현장에서는 곤란한 방향으로 나아가지 않도록, 전제를 전달해 두고 싶어집니다.

문서(Document)는 그를 위한 가드레일 (Guardrail) 역할도 할 수 있다고 생각합니다.

AI에게 전제를 전달하는 것만으로는 아직 조금 부족합니다.

AI에게 작업을 맡기려면, 작업 결과를 확인하는 메커니즘도 필요해집니다.

최근 자주 "하네스 (Harness)"라는 말을 접하게 됩니다.

제가 이해하기로 AI 개발에서의 하네스는, 대략 말하자면 AI가 변경한 결과를 확인하기 위한 메커니즘에 가깝습니다.

예를 들어, 다음과 같은 것입니다.

물론 인간이 확인하는 것은 중요합니다.

다만, 모든 것을 인간이 차이점 (Diff)을 읽으며 확인하는 것은 점점 힘들어질 것 같다는 느낌이 듭니다.

AI가 빠르게 구현할수록 확인해야 할 양도 늘어납니다.

그래서,

변경하면 이 테스트를 통과한다

이 명령어로 빌드(Build)한다

이 화면을 확인한다

이 API를 호출한다

이 관점에서 차이점을 설명한다

라는 메커니즘이 필요해집니다.

이는 AI를 신뢰하지 않기 위해서가 아니라, AI에게 안심하고 맡기기 위한 메커니즘에 가깝다고 생각합니다.

AI에게 맡길 때는 컨텍스트 (Context)와 하네스를 세트로 생각하게 됩니다.

컨텍스트는 AI가 작업하는 전제입니다.

• 무엇을 만드는가
• 무엇을 변경해서는 안 되는가
• 어떤 제약 사항이 있는가
• 어떤 판단 이력이 있는가
• 어떤 규칙을 지켜야 하는가

반면, 하네스는 AI가 작업한 이후의 확인입니다.

• 테스트가 통과하는가
• 빌드할 수 있는가
• 화면이 깨지지 않았는가
• API가 망가지지 않았는가
• 기대한 동작이 되고 있는가
• 인간이 마지막으로 확인해야 할 지점은 어디인가

이 두 가지가 있으면 AI에게 맡기는 작업이 조금 더 안정될 것 같다는 느낌이 듭니다.

반대로 컨텍스트도 하네스도 없는 상태에서 AI에게 맡기면, 상당히 AI의 추측에 의존하게 됩니다.

AI는 빠르게 진행해 줍니다.

하지만 어느 방향으로 가도 좋은지를 나타내는 전제와, 나아간 결과를 확인하는 메커니즘이 없으면 나중에 인간이 불안해집니다.

그렇기에 AI 시대의 문서는 단순히 읽히기 위한 것이 아니라, AI에게 맡기기 위한 토대가 되어갈 것이라고 생각합니다.

AI가 더 똑똑해지면 문서는 필요 없어질 것이다.

그렇게 보는 시각도 있을 것입니다.

확실히 AI가 코드를 읽을 수 있는 범위는 넓어질 것입니다.

코드로부터 구성을 정리하거나, 설계 자료를 만들거나, 영향 범위를 추측하는 능력도 높아질 것입니다.

하지만 그럼에도 코드에 남아 있지 않은 전제가 있습니다.

• 왜 그렇게 결정했는가
• 누구와 확인했는가
• 무엇을 스코프 (Scope) 외로 두었는가
• 어떤 판단을 보류했는가
• 어떤 제약을 수용했는가
• 어디를 인간이 마지막으로 확인하는가

이런 정보는 인간이 남기지 않으면 사라집니다.

그리고 AI가 작업하는 시대에는 그것이 단순히 인간을 위한 기록이 아니라, AI에게 전달하는 전제가 됩니다.

그렇게 생각하면 AI가 발달할수록 문서의 가치가 떨어지는 것이 아니라, 무엇을 남길 것인가, 어떻게 남길 것인가의 중요성이 커진다는 느낌이 듭니다.

AI 시대의 문서는 인간에게 설명하기 위한 것만은 아니게 될 것 같습니다.

AI에게 전제를 전달하기 위한 컨텍스트.

AI의 작업 결과를 확인하기 위한 하네스.

인간이 마지막으로 판단하기 위한 단서.

그런 역할이 늘어날 것이라고 생각합니다.

물론 모든 프로젝트에서 처음부터 완벽한 문서를 준비하는 것은 현실적이지 않습니다.

다만 AI에게 개발을 맡기는 상황이 늘어날수록,

• AI에게 무엇을 읽힐 것인가
• 어떤 전제를 남길 것인가
• 무엇을 검증할 수 있게 할 것인가
• 어디를 인간이 확인할 것인가

를 고민하는 상황은 늘어날 것 같습니다.

AI가 똑똑해질수록 문서는 필요 없어질 것이다.

처음에는 그렇게 보일지도 모릅니다.

하지만 지금의 저에게는 조금 반대로 보입니다.

AI가 똑똑해질수록, AI에게 전달하는 전제가 더 중요해집니다.

따라서 문서는 사라지는 것이 아니라, **인간과 AI가 동일한 전제하에 개발하기 위한 컨텍스트 (Context)**가 되어가는 것일지도 모릅니다.

저 또한 아직 시행착오를 겪는 중입니다.

당분간은 이 부분에 대해 계속 고민하게 될 것 같습니다.