AI와 사람이 함께 소프트웨어를 개발하려면 둘 다 현재의 도메인과 작업 상태를 이해할 수 있어야 한다. 하지만 AI와 사람은 같은 정보를 소비하는 방식이 다르다.
이 글은 같은 도메인 지식을 두 독자에게 적합한 형태로 제공하는 두 가지 방법을 권고한다.
이 글은 아무런 준비가 없는 저장소에서 프롬프트만으로 개발하는 방법을 이야기하지 않는다.
실제 AI 페어 코딩 환경에는 보통 품질 좋은 하니스가 이미 마련되어 있다. GitHub 저장소를 공유하면 AI는 작업 규칙, 코드 스타일, 테스트 방법, 명령어, 디렉터리 구조와 같은 기본 정보를 확인할 수 있다. 이러한 하니스는 AI가 저장소 안에서 일관된 방식으로 작업하도록 만드는 중요한 기반이다.
그러나 하니스가 잘 갖춰져 있어도 복합적인 기능 개발에서는 다음과 같은 실패가 발생한다.
이 글은 이런 실패를 줄이기 위한 안전장치로 외부 문서를 사용하는 방법을 제안한다.
AI가 작업하는 동안 원래 목적과 현재 상태를 반복해서 복원할 수 있도록, 도메인 지식과 태스크 진행 상태를 문서에 기록한다.
사람이 AI에게 매 순간 미세한 지침을 반복해서 전달하는 방식은 일반적인 기대와 다르다.
사용자는 대체로 하나의 의미 있는 태스크를 전달하고, AI가 다음 과정을 스스로 수행해 한 번에 해결하기를 기대한다.
작은 기능에서는 이 과정이 한정된 컨텍스트 안에서 무리 없이 끝날 수 있다. 하지만 여러 기능과 계층을 함께 다루는 태스크에서는 다른 문제가 생긴다.
LLM의 추론 호출은 이전 호출의 사용자·프로젝트 상태를 모델 내부에 영구적으로 유지하지 않는 stateless 실행이다.
Codex와 같은 코딩 에이전트의 호스트는 매 호출에 필요한 정보를 구성해 모델에 제공한다. 여기에는 다음과 같은 내용이 포함된다.
API나 에이전트 호스트가 대화 상태를 서버에 저장할 수는 있다. 그러나 이는 모델 외부의 상태 관리 계층이다. 모델의 추론은 호스트가 해당 호출에 제공한 컨텍스트에 의존한다.
이 구조에서 채팅 내역은 인간의 단기 기억(STM)과 비슷한 역할을 한다. 앞선 대화와 작업 결과를 다음 호출에 전달하여 연속적인 작업처럼 보이게 한다.
하지만 복합 태스크가 진행될수록 채팅 컨텍스트는 코드, 문서, 검색 결과와 툴 출력으로 빠르게 채워진다. 더 큰 컨텍스트 윈도우는 더 많은 정보를 담을 수 있게 하지만, 모든 정보가 같은 중요도로 유지되고 필요한 순간에 정확히 사용된다는 뜻은 아니다.
정보를 컨텍스트에 담고 있는 것과 태스크의 상태를 안정적으로 유지하는 것은 서로 다른 문제다.
태스크 초기에 전달된 요청, 비즈니스 규칙과 완료 조건은 작업 전체의 기준이다. 그러나 구현이 진행될수록 모델은 최근에 읽은 코드, 방금 발생한 오류, 마지막 테스트 결과와 같은 정보에 계속 반응해야 한다.
그 결과 실제 작업에서는 다음과 같은 현상이 나타날 수 있다.
AI가 처음에는 태스크를 올바르게 분해했더라도 후반에 일부 하위 작업을 누락할 수 있다. 마지막으로 수정한 기능이 동작하면 전체 요청도 완료되었다고 판단하기 쉽다.
코드는 현재 구현된 동작을 보여 주지만, 그 동작이 현재도 유효한 비즈니스 정책인지는 알려 주지 않는다. 오래된 정책이 코드에 남아 있다면 AI는 이를 현재 의도로 해석해 잘못된 방향으로 구현할 수 있다.
AI가 기능 사이의 비즈니스 관계를 모르면 요청받은 파일이나 동작은 수정하면서도 함께 변경되어야 할 다른 기능, 데이터, 정책과 테스트를 놓칠 수 있다.
빌드 성공, 특정 테스트 통과 또는 한 화면의 정상 동작은 전체 태스크의 완료 증거가 아니다. 최초 요청과 모든 완료 조건을 다시 확인하지 않으면 남은 작업이 있어도 완료를 선언할 수 있다.
문서는 사람을 위한 설명 자료에 그치지 않는다. AI가 작업의 목적과 현재 위치를 다시 불러오는 외부 기억장치가 될 수 있다.
채팅과 외부 문서는 다음과 같이 역할이 다르다.
| 구분 | 역할 | 한계 또는 특징 |
|---|---|---|
| 하니스 | 작업 절차, 도구와 저장소 규칙을 제공한다 | 현재 비즈니스 지식과 개별 태스크 상태를 모두 설명하지는 않는다 |
| 코드 | 현재 구현 상태를 보여 준다 | 현재의 비즈니스 의도와 만료된 정책을 구별하지 못한다 |
| 채팅 컨텍스트 | 현재 호출에 필요한 단기 맥락을 전달한다 | 긴 작업에서 다른 정보와 섞이고 중요도가 흐려질 수 있다 |
| 외부 문서 | 도메인 지식, 원래 요청과 작업 상태를 지속해서 보존한다 | 사람이 검토하고 AI가 반복해서 읽고 갱신할 수 있다 |
외부 문서는 저장소 또는 팀이 관리하는 공간에 남는다. 대화가 길어지거나 새로운 세션이 시작되어도 다시 읽을 수 있고, 사람도 그 내용을 검토할 수 있다.
도메인 문서는 현재 유효한 비즈니스 지식과 기능 사이의 관계를 기억한다.
예를 들면 다음과 같다.
AI는 코드를 현재 비즈니스 사실로 추측하기 전에 이 문서를 기준으로 삼는다. 코드와 문서가 충돌하면 어느 쪽이 현재 의도인지 확인한 뒤 함께 바로잡는다.
태스크 실행 문서는 하나의 복합 태스크가 어디까지 진행되었는지를 기억한다.
예를 들면 다음을 기록한다.
이 문서는 대화 안에서 한 번 작성하고 잊는 계획이 아니다. 작업이 진행되는 동안 계속 읽고 갱신하는 실행 상태다.
태스크 실행 문서에는 변하지 않아야 할 기준과 계속 바뀌는 상태가 함께 필요하다. 두 영역을 명확하게 분리해야 한다.
| 영역 | 기록할 내용 | 갱신 원칙 |
|---|---|---|
| 작업 계약 | 최초 요청, 비즈니스 규칙, 범위, 완료 조건 | 구현 결과에 맞춰 AI가 임의로 변경하지 않는다 |
| 실행 상태 | 작업 분해, 진행 상태, 발견 사항, 검증 결과, 남은 문제 | 작업할 때마다 현재 사실로 갱신한다 |
작업 계약을 고정하지 않으면 AI가 잘못된 구현에 맞춰 문서를 수정하고 완료 기준까지 낮출 수 있다. 구현 과정에서 계약을 변경해야 할 이유가 발견되면 기존 내용을 조용히 덮어쓰지 않는다. 변경 필요성과 영향을 기록하고 사용자의 판단이 필요한지 구분한다.
외부 문서의 효과는 문서를 한 번 작성하는 데서 나오지 않는다. AI가 작업 중 반복해서 읽고 기록하는 루프를 만들어야 한다.
AI는 사용자와 함께 요청을 구체화하고 다음 항목을 기록한다.
AI는 작업 계약을 실행 가능한 하위 태스크로 분해하고 의존 순서를 기록한다. 각 항목에는 완료 여부뿐 아니라 무엇으로 완료를 검증할지도 포함한다.
작업의 각 구간에서 AI는 관련 도메인 문서, 작업 계약과 현재 실행 상태를 다시 읽는다. 모든 문서를 무작정 다시 넣는 것이 아니라 이번 판단에 필요한 최소한의 기준과 상태를 불러온다.
현재 하위 태스크를 수행한 뒤 테스트, 빌드, 코드 확인 또는 사용자 시나리오로 결과를 검증한다.
완료한 항목, 검증 결과, 새로 발견한 영향과 남은 문제를 실행 상태에 기록한다. 코드 변경으로 도메인 계약이 달라졌다면 관련 도메인 문서도 같은 작업에서 갱신한다.
다음 호출은 갱신된 문서를 읽어 원래 목적, 현재 위치와 다음 작업을 복원한다. 최근 코드나 오류에만 의존하지 않고 전체 태스크의 흐름으로 돌아간다.
이를 하나의 제어 루프로 표현하면 다음과 같다.
문서에서 상태 복원 → 다음 작업 선택 → 코드 변경 → 검증 → 문서에 상태 저장 → 다시 상태 복원
AI는 “더 이상 할 일이 떠오르지 않는다”거나 “마지막 테스트가 통과했다”는 이유로 완료를 선언하지 않는다.
완료하기 전에 작업 계약을 다시 읽고 다음 내용을 확인한다.
완료는 모델의 주관적인 판단이 아니라 문서에 고정된 조건과 검증 증거의 대조 결과여야 한다.
처음부터 거대한 문서 체계를 만들 필요는 없다. 복합 태스크마다 다음 구조의 짧은 문서 하나로 시작할 수 있다.
| 작업 | 상태 | 검증 방법 | 결과 또는 발견 사항 |
|---|---|---|---|
| 관련 도메인과 코드 확인 | 대기 | 적용 규칙과 영향 범위 목록 | |
| 기능 A 변경 | 대기 | 관련 테스트 | |
| 연관 기능 B 확인 | 대기 | 회귀 테스트 | |
| 문서 동기화 | 대기 | 코드와 문서 대조 | |
| 전체 완료 검증 | 대기 | 최초 완료 조건 전체 대조 |
AI는 작업 전과 작업 중에 이 문서를 읽고, 각 단계가 끝날 때 상태와 증거를 갱신한다.
컨텍스트 문제를 해결하기 위해 매 호출마다 저장소의 모든 문서를 제공하면 같은 문제가 반복된다. 현재 태스크에 적용되는 도메인 규칙, 작업 계약, 진행 상태와 미완료 항목을 중심으로 읽는다.
문서의 목적은 구현을 설명하는 것만이 아니다. 구현이 최초 요청과 비즈니스 규칙을 지켰는지 판단하는 기준이다. 계약 변경과 단순한 진행 상태 갱신을 구별해야 한다.
“완료”라는 표시는 검증 방법과 결과가 함께 있을 때 의미가 있다. 테스트하지 못했거나 확인하지 못한 항목은 완료가 아니라 미검증 상태로 남긴다.
AI가 구현에 의존할 문서에는 현재 유효한 사실을 명확하게 표시한다. 과거 결정과 변경 경위가 필요하다면 현재 계약과 분리해 오래된 정책을 다시 구현하지 않도록 한다.
품질 좋은 하니스는 AI가 저장소에서 올바른 절차로 작업하도록 돕는다. 그러나 복합 태스크의 원래 목적, 현재 비즈니스 지식과 세부 진행 상태까지 자동으로 보존해 주지는 않는다.
Stateless 모델을 사용하는 코딩 에이전트는 채팅 컨텍스트를 STM처럼 활용한다. 하지만 긴 작업에서는 코드, 문서와 툴 결과가 누적되면서 초기 요청과 중요한 비즈니스 규칙이 흐려질 수 있다. 컨텍스트 윈도우를 키우는 것만으로는 작업 상태와 완료 조건을 안정적으로 유지하기 어렵다.
외부 문서는 이 한계를 보완한다.
컨텍스트는 작업에 필요한 재료를 제공하고, 외부 문서는 작업 전체의 상태와 방향을 유지한다.
이 방법의 목표는 AI에게 더 많은 정보를 한꺼번에 기억시키는 것이 아니다. AI가 필요한 순간마다 프로젝트가 소유한 문서에서 원래 목적과 현재 상태를 복원하여, 요청한 기능을 빠뜨리지 않고 끝까지 완료하게 만드는 것이다.
AI에게 코딩을 위임하는 환경에서 사람은 모든 구현 코드를 직접 작성하거나 세부 동작을 코드만으로 확인하지 않는다. 대신 무엇을 만들어야 하는지 지시하고, AI가 제안한 방향과 결과가 비즈니스 의도에 맞는지 판단한다.
이때 사람에게 더 중요해지는 것은 특정 코드의 문법보다 도메인 지식이다.
사람이 이러한 내용을 이해해야 AI에게 정확한 지침을 줄 수 있고, AI가 만든 결과도 제대로 검증할 수 있다.
현재 도메인 지식을 Markdown 형태로 저장소에 보관하는 방식이 널리 사용된다. Markdown은 AI가 읽고 수정하기에 유리하다.
따라서 Markdown은 AI가 참조할 도메인 지식의 원본으로 적합하다.
서식이 최소화된 긴 Markdown 문서는 사람에게 필요한 전체 그림을 충분히 보여 주지 못할 수 있다.
이는 단순한 읽기 편의의 문제가 아니다. 관계를 파악하기 어려우면 사람이 AI의 지시와 결과를 검증하기도 어려워진다.
사람을 위한 HTML 문서에서는 도메인 정보를 글의 나열에만 두지 않고 관계가 보이도록 표현한다.
예를 들면 다음과 같다.
HTML의 목적은 문서를 화려하게 꾸미는 것이 아니다. 사람이 중요한 규칙과 관계를 더 빠르고 정확하게 인식하도록 정보 구조를 시각화하는 것이다.
AI는 현재 요청을 중심으로 코드를 탐색하고 변경한다. 그러나 사람은 현재 요청과 직접 분리되어 보이는 주변 기능도 알고 있어야 한다.
별도의 기능처럼 보여도 다음과 같은 관계가 있을 수 있기 때문이다.
사람이 전체 도메인 관계를 알고 있으면 AI가 프롬프트에 언급된 부분만 수정하거나 관련 기능을 놓칠 때 이를 발견할 수 있다.
AI는 현재 태스크를 깊게 수행하고, 사람은 그 태스크가 전체 도메인 안에서 올바른 위치와 방향을 유지하는지 확인한다.
사람의 검증을 구현 완료 후의 시연 테스트로 한정할 필요는 없다. AI가 작업하는 도중에도 사람은 제공된 정보를 보고 방향을 판단할 수 있다.
AI가 공유하는 다음 내용을 HTML 도메인 문서와 비교한다.
사람은 이 과정에서 다음과 같이 개입할 수 있다.
이런 개입은 AI의 구현이 모두 끝난 뒤 잘못을 발견하는 것보다 빠르고 비용이 적다. 사람용 HTML은 결과 검수 자료인 동시에 작업 중 지침을 조정하기 위한 인터페이스다.
Markdown과 HTML을 서로 독립된 문서로 관리하면 같은 도메인 지식이 다르게 기록될 수 있다. 그러면 AI와 사람이 서로 다른 사실을 기준으로 판단하게 된다.
따라서 두 문서는 별개의 진실이 아니라 하나의 지식을 위한 두 개의 표현으로 관리한다.
| 표현 | 주요 독자 | 목적 |
|---|---|---|
| Markdown | AI와 개발자 | 적은 컨텍스트로 정확한 규칙과 계약을 전달하고 버전 관리한다 |
| HTML | 코딩을 위임하고 검증하는 사람 | 규칙, 흐름과 관계를 이해하고 AI의 작업에 개입한다 |
Markdown을 기준 문서로 두고 HTML을 그 내용의 사람용 투영으로 만들면 두 표현의 일관성을 유지하기 쉽다.
Markdown 변경 → HTML 생성 또는 동기화 → 내용과 관계 검증 → 사람에게 공유
HTML에서 추가한 도표와 설명도 어떤 Markdown 규칙에서 나온 것인지 추적할 수 있어야 한다. 그래야 시각화가 원문의 의미를 바꾸거나 오래된 내용을 계속 보여 주는 문제를 찾을 수 있다.
사람이 도메인을 이해하고 AI 작업을 검증하려면 HTML에 다음 정보가 잘 드러나는 것이 좋다.
제품이나 업무가 해결하는 문제, 주요 참여자와 핵심 흐름을 먼저 보여 준다.
용어의 의미, 적용 조건, 예외와 금지되는 동작을 일반 설명과 구분한다.
기능, 데이터, 사용자와 외부 시스템이 어떻게 연결되는지 시각적으로 보여 준다.
정상 흐름뿐 아니라 조건별 분기, 실패와 예외 흐름도 함께 표현한다.
하나의 기능이나 규칙이 바뀔 때 확인해야 할 관련 기능과 데이터를 연결한다.
현재 확정된 내용과 아직 정하지 않은 내용을 명확하게 구분한다.
관련 Markdown 원문으로 이동할 수 있는 링크와 HTML이 어느 버전의 원문에서 만들어졌는지를 표시한다.
목차, 문서 간 연결, 검색과 반응형 레이아웃을 제공해 회의나 모바일 환경에서도 필요한 관계를 빠르게 확인하게 한다.
사람용 HTML도 한 번 만들어 두고 작업이 끝난 뒤에만 보는 산출물이 아니다.
이를 짧게 표현하면 다음과 같다.
AI는 Markdown으로 맥락을 복원하고, 사람은 HTML로 전체 관계를 확인하며, 두 문서는 코드 변경과 함께 동기화된다.
사람용 HTML 도메인 문서는 단순히 Markdown을 편하게 읽기 위한 문서가 아니다.
사람용 HTML은 도메인 지식을 읽는 문서이면서, AI의 작업을 관찰하고 검증하고 조정하기 위한 인터페이스다.
AI와 사람에게 필요한 문서는 경쟁 관계가 아니다. 같은 도메인 지식을 각 독자에게 적합한 방식으로 제공한다.
| 대상 | 문서의 역할 | 기대 효과 |
|---|---|---|
| AI | Markdown을 외부 기억장치로 반복해서 읽고 갱신한다 | 원래 요청, 도메인 규칙과 작업 상태를 잃지 않고 복합 태스크를 완료한다 |
| 사람 | HTML에서 중요한 규칙과 관계를 확인한다 | AI의 계획과 결과를 검증하고 필요한 순간에 작업 방향을 수정한다 |
AI의 외부 기억만 있고 사람이 전체 도메인을 이해하지 못하면 잘못된 문서나 결과를 사람이 검증하기 어렵다. 반대로 사람용 시각화만 있고 AI가 읽을 간결한 원본과 실행 상태가 없으면 AI가 긴 작업 중 맥락을 잃을 수 있다.
두 표현을 함께 사용하면 하나의 순환 구조가 만들어진다.
Markdown은 AI가 정확히 작업하도록 돕고, HTML은 사람이 그 작업을 정확히 감독하도록 돕는다. 사람의 검토와 코드 변경으로 달라진 지식은 다시 Markdown과 HTML에 반영된다.