코드는 이제 저렴한 아티팩트, 스펙은 자산

출처: Dev.to

지난 몇 주간 제가 가장 크게 생각한 변화는 다음과 같습니다: 시간을 더 많이 디자인에 투자하고, 사양과 구현 계획을 수작으로 적는 시간을 줄이고 싶습니다. 놀라운 점은 AI가 이를 가능하게 했다는 것이며, 이는 엔지니어링 판단을 대체하는 것이 아니라 그 적용 위치를 바꾸었다는 것입니다. 오늘날 저는 점점 더 AI에게 사양, 구현 계획, 심지어 코드를 초안으로 작성하도록 맡깁니다. 제 역할은 의도 정의, 제약 조건 식별, 그리고 결정을 검토하는 것으로 전환되었습니다. 글 자체는 이제 과정 중 가장 가치가 낮은 부분이 되었습니다. 제가 이야기하는 사양은 전통적인 문서가 아닙니다. 앞으로의 엔지니어가 위키를 둘러보기 위해 읽는 것이 아니라, 작업을 이어갈 다음 AI 세션을 위해 쓰였으며, 처음부터 다시 설명할 필요 없이 작업을 이어갈 수 있도록 설계되었습니다. 이것은 형태에 변화를 줍니다. 서술적 설명 대신 다음과 같은 내용에 집중합니다: 요구사항 제약 조건 수용 기준 검증 단계 즉, 읽히기보다 실행되는 데 목적을 두고 설계되었습니다. 대상 독자는 더 이상 인간이 아니라 다음 기여자 — 엔지니어든 AI 에이전트든입니다.

최근 제가 집중하고 있는 프로젝트는 기존 제품을 새로운 아키텍처에 맞게 재구성하면서도 기존 비즈니스 로직을 변경하지 않는 것입니다. 이 조합은 거의 모든 경우에 제약 조건에 대한 문제로 귀결됩니다:

• 준수해야 할 참조 아키텍처
• 비즈니스 동작의 진실 출처가 되는 레거시 시스템
• 승인된 경계를 초과해 해석할 수 없는 불투명한 통합 응답
• 수정할 수 없는 상태‑별 규칙

이건 CRUD 애플리케이션 문제도 아니고, 제약 조건 관리 문제입니다. 제약 조건은 AI가 명확히 포착할 경우에 효과적으로 처리할 수 있는 정보의 유형과 정확히 일치합니다.

시간이 지남에 따라 우리 워크플로우는 다음과 같은 의도적 검토 게이트 시리즈로 진화했습니다: 의도 → AI 사양 → 인간 검토 → AI 구현 계획 → 인간 검토 → AI 코드 생성 → 테스트 및 검증

제가 제공하는 것은: 목표 요구사항 제약 조건 아키텍처 경계를

AI가 사양 초안을 먼저 작성합니다. 저는 이를 검토합니다. AI가 구현 계획을 작성합니다. 다시 검토합니다. 그 후 코드 생성이 시작됩니다. 결과적으로 저는 이전보다 훨씬 적게 글을 쓰지만, 훨씬 더 철저히 검토하고 있습니다. 그리고 이것이 현재 대부분의 엔지니어링 가치가 존재하는 곳입니다.

우리의 사양은 의도적으로 테스트 계획과 유사한 구조로 설계되어 있습니다. 사양은 코드가 어떻게 작동하는지 설명하지 않으며, 관측 가능한 요구사항을 정의합니다.

예를 들어, 리팩터링 사양에는 다음과 같은 내용이 포함될 수 있습니다: 요구사항 제약 조건 수용 기준 검증 단계

The specification defines what must be true. how to make it true.

오늘날 제가 가장 중요한 일은 쓰는 것이 아니라, 어떤 제약 조건이 realmente(진정한) 부하를 지탱하는지 판단하는 것입니다.

아키텍처 기반 (필수 — 위반 시 전체가 깨질 수 있음):

• 데이터베이스 초기화 전략
• 배포 모델
• 통합 경계
• 런타임 소유 규칙

관습 (유용하지만 필수적이지 않음):

• 패키지 명명
• 폴더 조직
• 서비스 명명 패턴

그 후에는 의도적인 예외가 있는데, 이는 잘못 보이지만 실제 운영상의 정당한 이유로 존재합니다. 이러한 예외는 가장 위험할 수 있습니다.

의도적으로 청소를 진행하면 기술 부채처럼 보이지만 실제로는 호환성을 보존하던 요소를 제거함으로써 생산 시스템을 의도치 않게 깨뜨릴 수 있습니다.

AI가 사양을 만들면 제 주요 검토 질문은 간단합니다:

• 그것이 로드‑베어링(핵심) 제약 조건을 올바르게 식별했는가?

이것은 여전히 인간의 판단에 기반한 결정이며, 스스로 초안을 작성하는 것보다 훨씬 더 가치 있는 시간 활용법입니다.

이것은 AI 보조 개발에 대한 제 생각을 바꾸게 만든 깨달음입니다. 개별 AI 세션은 일시적인 기여자 역할을 합니다. 나타나고, 기여하고, 사라집니다. 가치는 어느 한 세션이 특히 지능적이라기보다는, 모든 세션이 동일한 진원 — 사양, 구현 계획, ADR(아키텍처 결정 기록), 관습, 상태 추적 — 을 공유한다는 데서 나옵니다.

이러한 아티팩트들은 프로젝트의 장기 기억이 됩니다. AI 세션은 일시적이며, 메모리는 영속됩니다.

저는 이 교훈을 고통스럽게 배웠습니다.

한때 우리의 문서가 흐려졌습니다. ADR은 데이터베이스 스키마가 Liquibase 대신 시작 스크립트를 통해 초기화된다고 명시했지만:

• 변경 로그(changelog)에는 여전히 스키마 부트스트랩 로직이 포함되어 있었음
• README에서는 다른 전략을 설명하고 있었음
• 코드 주석은 전혀 다른 내용을 주장하고 있었음

세 개의 아티팩트, 세 가지 서로 다른 이야기.

새로운 기여자(또는 AI 세션)가 저장소를 읽으면 즉시 잘못된 정신 모델을 습득하게 됩니다.

수정 방법은 간단했습니다. 우리는 단순히 물었습니다:

• 깨끗한 환경에서 빌드할 때 실제로는 어떤 일이 발생했는가?

운영 동작이 진실의 심판자가 되었습니다. 현실을 검증한 후 우리는:

• 불필요한 아티팩트를 제거했습니다.
• 문서를 업데이트했습니다.
• ADR과 구현 계획을 정렬했습니다.
• 프로젝트 상태 추적을 최신화했습니다.

결과는 단순히 문서가 청소된 것이 아니라, 진실에 대한 신뢰를 회복한 것이었습니다. 이것이 향후 기여자들이 더 빠르게 이동할 수 있게 해줍니다.

다음은 이 내용이 실제 저장소 구조로 어떻게 반영되는지를 보여줍니다:

state-retail/
├── CLAUDE.md                   # 워크플로우 — 인간 검토 게이트. 먼저 읽으세요.
├── README.md                   # 진입점: 구조, 문서 맵, 스키마 전략, 실행 방법.
├── status.md                   # 모든 사양/계획 및 그 상태를 담은 살아있는 인덱스.

├── specs/                      # 목적 (왜)
│   ├── CONVENTIONS.md          # 권위 — 중복 시 승리
│   ├── architecture.md         # 레이어링 및 명명 참고
│   ├── global-rules.md         # 전반적 규칙
│   ├── infra.md                # DB / Docker / 스키마 관리 계약
│   └── .md                     # 예시 사양 파일

├── plan/                       # 방법, specs와 미러링
│   └── .md                     # 계획용 마크다운 파일

├── rules/                      # 계층별 코딩 관습
│   └── domain / dao / service / application / api

└── docs/adr/                   # 중요한 결정이 내려진 이유
    └── NNNN-.md          # 수락된 후 불변; 새로운 ADR로 대체

AI는 사양, 계획, 코드를 생성하는 능력이 점점 커지고 있습니다. 그것은 비즈니스에 가장 중요한 제약 조건을 정확히 판단하는 데 믿을 수 없습니다. 이 책임은 여전히 소프트웨어 엔지니어의 몫입니다.

복잡하고 엄격히 규제되는 시스템을 구축하는 조직에 있어 이는 단순한 생산성 향상 이상입니다. 이는 매 프로젝트가 공유 메모리 없이 빈 페이지가 아닌, 실행 가능한 지식을 축적하도록 하는 방법입니다. 코드는 점점 더 저렴한 산물로 여겨집니다. 사양은 자산이다.