Specification-First 개발로 문서화 자동화 및 AI 컨텍스트 손실 해결

Context

AI 보조 코딩 시 복잡도 증가에 따른 AI의 컨텍스트 소실과 일관성 없는 코드 생성 문제 발생. 기존의 사후 문서화 방식은 개발자의 리소스 부족으로 인해 구현 의도(the why)를 기록하지 못하는 한계 노출.

Technical Solution

• .agentsmith/phases/ 디렉토리를 통한 상태 기반(planned/active/done) 개발 워크플로우 설계
• 코드 작성 전 .md 파일로 명세(Specification)를 선행 정의하여 AI의 설계 방향성 강제
• context.yaml을 활용한 상태 관리로 AI의 Token 낭비를 방지하고 세션 재시작 시 즉각적인 복구 구현
• decisions.md에 대안과 근거를 강제 기록하는 Log-first 전략으로 구현 결정 사항의 추적성 확보
• 명세-구현-검증-기록의 순차적 Phase 단계를 정의하여 AI의 무분별한 코드 생성을 제어하는 가드레일 구축
• 개발 과정의 부산물인 Phase 파일을 합성하여 기술 문서를 자동 생성하는 Self-documentation 구조 채택