AI에게 바로 만들라고 하지 않는 이유

그럴듯한 답을 바로 구현하지 않고, 대화와 문서 인덱스로 판단의 기반을 만드는 개발 방식.

2026년 8월 15일

처음에는 AI를 꽤 단순하게 썼습니다. 만들고 싶은 것을 말하고, 나온 답이 그럴듯하면 그대로 이어서 만들었습니다. 빠르고 편했습니다.

문제는 AI가 코드를 못 짜서 생기지 않았습니다. 제가 아직 결정하지 않은 것까지 이미 결정된 것처럼 담아 답을 만들었다는 데 있었습니다. 나중에는 코드를 고치는 것보다, 코드에 들어가기 전에 제가 건너뛴 질문을 다시 고치는 데 더 많은 시간을 쓰게 됐습니다.

그럴듯한 답은, 아직 답이 아닐 수 있다

프로젝트에서 AI가 참고할 기억 시스템을 만들 때도 비슷했습니다. 처음에는 “관련된 기억을 작업에 잘 넣어 주면 되지 않을까?” 정도로 생각했습니다. AI는 확실한 기억 몇 개만 먼저 넣고, 애매한 기억은 후보로 두자는 방안을 바로 제안했습니다.

처음에는 맞는 말처럼 보였습니다. 하지만 구현을 생각할수록 막혔습니다. 우리는 아직 기억이 무엇인지 정하지 않았기 때문입니다.

확정된 제품 결정과 작업 중에 적어 둔 메모는 같은 방식으로 다루면 안 됩니다. 이미 폐기한 가설, 다음 작업에서 꼭 알아야 하는 규칙, 나중에 참고만 하면 되는 배경 정보도 마찬가지입니다. 저장 형태와 출처, 언제까지 유효한지를 정하지 않은 채 “무엇을 먼저 넣을까”부터 논의하고 있었던 겁니다.

그래서 저는 대화를 멈추고 다시 물었습니다.

그 기준을 정하기 전에, 이 기억이 어떤 형태로 저장되는지부터 알아야 하지 않을까?

질문은 다시 아래로 돌아갔습니다.

이 정보는 누가, 언제 남기는가?
확정된 결정과 검토 중인 생각은 어떻게 구분하는가?
다음 작업에서 반드시 알아야 하는 것은 무엇인가?
필요할 때 검색해서 가져오면 되는 정보는 무엇인가?

이 과정을 거치면 AI의 다음 답도 달라집니다. 답을 받는 속도는 조금 느려질 수 있습니다. 대신 나중에 뒤집어야 할 전제는 훨씬 줄어듭니다.

대화가 끝나면, 결정만 남긴다

대화 전체를 기억으로 쌓아 두는 것은 좋은 방법이 아니었습니다. 나중에 다시 읽기도 어렵고, 확정된 내용과 순간적인 아이디어가 섞이기 때문입니다.

대화가 어느 정도 정리되면 저는 아래 네 가지만 남기려고 합니다.

지금 풀려는 문제는 무엇인가
이번에 확정한 선택은 무엇인가
왜 이 선택을 했는가
아직 결정하지 않은 것은 무엇인가

예를 들어 “기억을 많이 넣을까, 적게 넣을까”의 결론은 단순히 적게 넣는다가 아닙니다. “처음에는 확실하고 작은 정보만 쓰고, 누락 위험이 큰 규칙은 따로 보존한다. 작업 중 필요해지면 후보 정보를 추가로 찾는다”처럼 이유와 예외까지 남겨야 다음에도 같은 판단을 할 수 있습니다.

이 기록은 AI에게 시키기 위한 프롬프트 모음이 아닙니다. 미래의 저와 다음 작업의 AI가 왜 이렇게 만들었는지 다시 이해하기 위한 기준입니다.

문서를 많이 쌓는 것이 아니라, 찾아갈 길을 만든다

이 기준을 실제 프로젝트에 적용하면서 docs를 제품, 기능, 아키텍처, 엔지니어링, 운영, 에이전트 작업 방식처럼 역할별로 나눴습니다. 핵심은 마크다운 파일의 개수가 아닙니다. 새 작업이 들어왔을 때, 사람이든 AI든 필요한 기준으로 빠르게 도착할 수 있어야 합니다.

문서 구조는 대략 이렇게 시작합니다.

docs/
  00-index.md             # 모든 작업의 출발점
  product/README.md       # 제품 범위와 정책
  features/README.md      # 역할별 기능
  architecture/README.md  # 모듈 경계와 공통 구조
  engineering/README.md   # 구현 계약과 개발 규칙
  ops/README.md           # 운영과 검수 기준
  agent/README.md         # AI·개발자 작업 방식
  _generated/doc-map.md   # 메타데이터 기반 자동 문서맵

00-index.md는 단순한 목차가 아닙니다. “이번 일은 제품 범위를 바꾸는가?”, “권한이나 데이터 구조를 건드리는가?”, “디자인만 수정하는가?”처럼 작업의 성격을 먼저 나누고, 어디부터 읽어야 하는지 안내합니다.

그다음 각 영역의 README가 세부 문서로 연결합니다. 예를 들어 예약 기능을 고친다면 제품 요구사항만 읽고 끝낼 수 없습니다. 예약 상태가 어떻게 바뀌는지, 결제와 어떤 관계인지, 어떤 역할이 어디까지 수정할 수 있는지, 변경 이력이 필요한지를 함께 봐야 합니다. 반대로 디자인 여백을 다듬는 작업에 결제 정책 문서까지 모두 넣는 것은 오히려 판단을 흐립니다.

그래서 인덱스는 “무엇을 읽어야 할까”뿐 아니라 무엇을 지금 읽지 않아도 되는가까지 정하는 장치가 됩니다.

AI가 필요한 문서만 읽게 하는 방법

모든 문서를 한 번에 AI에게 넣지 않습니다. 컨텍스트가 많아진다고 이해가 깊어지는 것은 아니기 때문입니다. 저는 작업을 시작할 때 다음 순서로 문서를 찾습니다.

문서 홈에서 작업의 성격을 분류합니다.
해당 영역의 인덱스에서 기준 문서를 찾습니다.
기능·아키텍처·구현 규칙 중 이번 변경에 필요한 문서만 묶습니다.
구현 중 새 결정이 생기면, 관련 문서를 먼저 갱신합니다.

새 문서도 아무 폴더에나 만들지 않습니다. 먼저 제품 문서인지, 아키텍처 문서인지, 운영 기준인지 위치를 정합니다. 문서 상단에는 제목과 상태뿐 아니라 문서 종류, 담당 영역, 우선 읽어야 하는 역할, 관련 화면과 모듈을 적습니다. 이 메타데이터를 바탕으로 자동 문서맵을 만들면, 문서가 많아져도 특정 작업에 필요한 기준을 빠르게 찾을 수 있습니다.

문서끼리의 링크도 중요합니다. 제품 문서에서 관련 아키텍처 문서로, 아키텍처 문서에서 운영 기준과 구현 규칙으로 다시 이어집니다. 한 문서가 모든 것을 설명하는 대신, 각 문서는 자기 책임만 설명하고 다음 판단에 필요한 문서로 길을 열어 둡니다.

폴더로 한 번, 메타데이터로 한 번 좁힌다

폴더 구조만으로는 문서가 많아졌을 때 부족합니다. architecture 안에서도 예약, 권한, 결제, 파일 처리처럼 서로 다른 기준이 섞이기 때문입니다. 그래서 주요 문서에는 이런 메타데이터를 함께 둡니다.

title: 예약 상태 전이 기준
status: active
doc_type: architecture
owner_lane: backend
required_for: [backend-agent, frontend-integration-agent]
surface: [main-app, clinic-admin]
modules: [reservation, payment]
tags: [예약, 상태, 결제, 취소]

이 값들은 문서 제목을 예쁘게 꾸미기 위한 것이 아닙니다. 자동 문서맵에서 backend 담당 문서, reservation 모듈 문서, clinic-admin 화면과 관련된 문서처럼 다시 묶어 볼 수 있게 하는 검색 인덱스입니다.

예를 들어 “병원 예약을 취소할 때 결제 처리도 바꿔야 한다”는 작업이 들어오면, 먼저 reservation과 payment 모듈로 후보 문서를 좁힙니다. 그다음 clinic-admin과 main-app에 영향을 주는지 확인하고, 해당 문서가 요구하는 백엔드·프론트 작업 기준을 읽습니다. 마지막으로 문서 본문 검색으로 취소, 환불, 특정 상태값처럼 더 구체적인 근거를 찾습니다.

정리하면 검색도 두 단계입니다. 메타데이터와 태그로 읽을 문서의 범위를 먼저 줄이고, 본문 검색과 문서 링크로 지금 결정에 필요한 근거를 찾습니다. 태그가 본문을 대체하는 것은 아닙니다. AI에게 문서 전체를 던지기 전에, 어디를 읽어야 할지 알려 주는 표지판에 가깝습니다.

구현보다 먼저, 판단의 순서를 남긴다

이 방식이 처음부터 모든 답을 맞춰 주지는 않습니다. 개발하다 보면 새로운 사실이 나오고, 처음의 결정이 틀렸다는 것도 알게 됩니다.

그때 중요한 것은 코드를 먼저 고치고 문서를 나중에 따라 쓰는 습관으로 돌아가지 않는 일입니다. 무엇이 달라졌는지 다시 대화하고, 결정 기록을 고친 뒤, 그 기준으로 구현을 바꿉니다. 그래야 다음 작업에서 AI가 오래된 전제를 들고 오지 않습니다.

AI를 쓰면 구현 속도는 빨라집니다. 하지만 문제를 정의하고, 질문의 순서를 바로잡고, 무엇을 결정으로 남길지 고르는 일까지 대신해 주지는 않습니다.

저는 그 일을 사람이 해야 한다고 생각합니다. AI에게 일을 맡긴다는 것은 답을 받아 적는 일이 아니라, 더 좋은 질문을 함께 만들고 그 답이 다음 판단에도 남도록 구조를 만드는 일에 가깝습니다.