Before You Rely on AI for Coding, Fix Your Docs First

Context

AI 코드 생성 도구(ChatGPT, Claude, Gemini, Copilot, Cursor, Zed 등)가 보편화되면서 프로젝트 문서가 부족하거나 약할 경우 AI가 시스템 컨텍스트를 추측하게 되어 할루시네이션, 중복 로직, 엣지 케이스 오류, 프로덕션 환경에서의 장애를 야기하는 문제가 발생했다.

Technical Solution

• AGENTS.md (.cursorrules) 파일 도입: UI 프레임워크, 상태 관리, 로깅 표준 등 기술 스택 규칙을 마크다운으로 정의해 루트 디렉토리에 배치
• 서비스/모듈별 README 작성: 각 컴포넌트의 목적, 로컬 실행 방법, 입출력, 의존성 관계를 평문으로 기술
• API/데이터 계약 명시: OpenAPI/Swagger 파일 또는 GraphQL 스키마와 예제 요청/응답을 정의
• 아키텍처 결정 기록(ADR) 작성: 중요한 설계 선택의 배경, 선택지, 트레이드오프를 간단한 노트로 기록
• AI와 문서의 피드백 루프 구성: 문서 포맷팅을 AI에 요청하거나, 문서를 프롬프트 컨텍스트로 제공하거나, git diff 기반 문서 갭 탐지

Key Takeaway

코드는 빠르게 생성되지만 이해는 비용이 크므로, AI 도구에 의존하기 전에 단순하고 신뢰할 수 있는 문서 4가지를 먼저 정비하는 것이 중요하다. 이는 팀의 Slack 메시지, 회의, 개인 메모리에 산재된 비즈니스 규칙과 결정 내역을 AI가 접근 가능한 형태로 변환해 AI의 정확성과 팀의 생산성을 동시에 높인다.