AI가 우리에게 좋은 코드를 쓰도록 강요하고 있다

• AI 에이전트가 코드 작성의 중심에 들어오면서, 테스트, 문서화, 정적 타이핑 등 기존의 ‘선택적’ 모범 사례들이 이제 필수 요소로 변함
• 100% 코드 커버리지를 요구해, 모든 코드 라인이 실제로 검증되고 실행 예제로 뒷받침되도록 함
• 디렉터리 구조와 파일 네이밍을 명확히 하여 LLM이 코드베이스를 탐색하기 쉽게 만들고, 작은 단위의 파일 구성을 권장
• 빠르고 일시적이며 동시 실행 가능한 개발 환경을 구축해, 여러 에이전트가 병렬로 작업할 수 있도록 함
• 정적 타입 시스템과 자동화된 품질 관리 도구를 통해 AI가 신뢰할 수 있는 코드 생태계를 유지하는 것이 핵심임

AI와 ‘좋은 코드’의 필수성

• 오랜 기간 개발자들은 테스트, 문서화, 작은 모듈, 정적 타이핑 등을 좋은 코드의 기준으로 인식했지만, 현실에서는 종종 생략됨
• 그러나 AI 에이전트는 스스로 코드 정리를 잘 하지 못하므로, 이러한 모범 사례가 반드시 필요함
• 에이전트가 잘못된 방향으로 작동하지 않도록 명확한 가드레일 설정과 강제 실행이 필수
• 견고한 가드레일이 있으면 LLM은 올바른 경로로만 수렴하며, 불완전한 환경에서는 문제를 증폭시킴

100% 코드 커버리지

• 팀은 100% 코드 커버리지를 의무화하고 있으며, 이는 단순한 버그 방지가 아니라 에이전트가 작성한 모든 코드의 동작을 검증하기 위함
• 95%나 99.99% 커버리지에서는 테스트되지 않은 코드의 출처가 불분명하지만, 100%에서는 모든 미검증 라인이 명확히 식별 가능
• 커버리지 리포트는 테스트해야 할 목록으로 활용되며, LLM이 코드 변경 시 반드시 실행 가능한 예제를 제시해야 함
• 이 접근은 도달 불가능한 코드 제거, 엣지 케이스 명시, 코드 리뷰 효율 향상 등의 부수 효과를 가짐

네임스페이스와 파일 구조

• 에이전트는 파일 시스템을 통해 코드베이스를 탐색하므로, 디렉터리 구조와 파일 이름이 중요한 인터페이스 역할을 함
• ./billing/invoices/compute.ts 같은 명확한 경로는 ./utils/helpers.ts보다 훨씬 많은 정보를 전달
• 작고 잘 정의된 파일 단위를 선호해야 하며, 이는 LLM이 파일 전체를 문맥에 로드할 수 있게 해 성능 저하를 방지함
• 이러한 구조화는 에이전트의 탐색 속도와 정확도 향상으로 이어짐

빠르고 일시적이며 동시 실행 가능한 개발 환경

• 기존의 단일 개발 환경 대신, 에이전트 기반 개발에서는 여러 프로세스를 병렬로 관리하는 형태로 전환됨
• Fast: 테스트와 검증 절차가 빠르게 실행되어야 하며, 팀은 10,000개 이상의 어서션을 1분 내에 완료하도록 최적화
  • 고도 병렬화, 강한 격리, 서드파티 호출 캐싱 레이어를 통해 속도 확보
• Ephemeral: new-feature <name> 명령으로 1~2초 내 새 환경 생성, 자동 설정 및 에이전트 실행
  • 수동 설정이 필요하면 사용 빈도가 급감하므로, 완전 자동화가 핵심
• Concurrent: 여러 개발 환경을 동시에 실행할 수 있도록 포트, DB, 캐시 등 충돌 방지 설정 필요
  • Docker를 활용하거나 환경 변수 기반으로 격리 구성

엔드투엔드 타입 시스템과 자동화된 품질 관리

• 가능한 많은 모범 사례를 자동화해 LLM의 자유도를 줄이고, 일관된 품질을 유지
• 자동 린터와 포매터를 엄격히 설정해, LLM이 작업을 마칠 때마다 자동 수정 적용
• 정적 타입 언어 사용을 권장하며, 특히 TypeScript를 중심으로 강력한 타입 시스템을 활용
  • UserId, WorkspaceSlug, SignedWebhookPayload 같은 의미 있는 타입명을 통해 코드 의도를 명확히 표현
• OpenAPI를 통해 프론트엔드와 백엔드 간 타입 일치 유지
• Postgres의 타입 시스템과 트리거를 활용해 데이터 무결성 확보, Kysely로 타입 안전한 클라이언트 생성
• 모든 서드파티 클라이언트도 정확한 타입 정의를 갖추거나 래핑하여 사용

결론: AI 시대의 코드 품질 재정의

• 에이전트는 피로하지 않고 뛰어난 코더지만, 그 성능은 환경의 품질에 의존
• ‘좋은 코드’는 더 이상 선택이 아니라 AI가 제대로 작동하기 위한 전제 조건
• 초기 세팅은 부담처럼 느껴지지만, 이는 오랫동안 미뤄온 필수 투자
• 개발 리더십의 지원 아래, AI 친화적 코드베이스 구축을 목표로 해야 함