AI 코딩, 프롬프트에서 사양으로 전환

이 방법론은 프롬프트 우선 AI 코딩의 한계를 넘어 구조화된 사양에 중점을 둡니다.

이 워크플로우는 GitHub Enterprise, GitHub Copilot, Spekit을 통합하여 강력하고 재현 가능한 소프트웨어를 개발하기 위한 응집력 있는 환경을 만듭니다.

프롬프트는 일반적으로 비공개적이고 임시적이며 명확한 검토 메커니즘이 부족하여 엔터프라이즈급 개발의 약한 기반이 됩니다.

이러한 접근 방식은 공유된 이해와 추적성의 부족으로 인해 프로젝트 요구 사항에서 벗어나는 코드를 초래할 수 있습니다.

제안된 근본적인 변화는 프롬프트를 기본 아티팩트로 취급하는 것을 중단하고 대신 사양을 격상시키는 것입니다. 이 전환은 프로젝트의 핵심 문서가 영구적이고 검토 가능하며 버전 제어되도록 보장합니다.

사양을 주요 아티팩트로 만들면 팀은 대규모 및 장기 소프트웨어 개발에 중요한 더 큰 일관성과 유지 보수성을 달성할 수 있습니다.

헌법은 보안 표준 및 아키텍처 원칙과 같이 단일 프로젝트나 팀보다 광범위한 기본적이고 깨지지 않는 기업 규칙을 정의합니다.

사양 단계는 애플리케이션의 기능적 요구 사항을 설명하며, 기술 구현 세부 사항을 다루지 않고 '무엇을' 해야 하는지에 중점을 둡니다. 여기에는 높은 수준의 사용자 스토리와 원하는 동작이 포함됩니다.

계획 단계는 이러한 기능적 요구 사항을 기술 사양으로 변환하여 기술 스택, 배포 대상 및 상세한 아키텍처 선택 사항을 설명합니다. 마지막으로, 작업 단계는 프로젝트를 더 작고 관리하기 쉬운 논리적 청크로 분해하여 구현할 준비를 합니다.

헌법, 사양, 계획을 포함한 모든 문서는 철저한 사람의 검토를 거쳐야 합니다.

이 포괄적인 감사는 품질을 보장하고, 프로젝트 요구 사항 준수 여부를 확인하며, 팀의 정렬을 촉진하여 개발 주기 전반에 걸쳐 오해나 오류가 전파되는 것을 방지합니다.

사양 중심 개발의 핵심 원칙은 사양을 Git 저장소 내에서 영구적인 아티팩트로 만드는 것입니다. 사양을 저장소의 히스토리에 통합함으로써 코드를 포함한 모든 것이 버전 제어되고 추적 가능해집니다.

이를 통해 모든 새로운 기능 구현 또는 프로젝트 반복은 잘 정의되고 역사적으로 문서화된 기반에서 시작될 수 있어 반복 가능하고 일관된 개발 프로세스를 촉진합니다.

시작하려면 개발자는 SpecIt과 그 Specify CLI 도구를 설치해야 합니다. 프로세스는 터미널을 열고 'specify init' 명령을 실행하는 것으로 시작됩니다.

초기화 중에 사용자는 선호하는 AI 통합 도구를 선택하며, GitHub Copilot이 일반적인 선택이며, Windows 환경용 PowerShell과 같은 셸 기본 설정을 구성합니다.

초기화 시 SpecIt은 프로젝트 디렉토리 내에 'specify' 폴더를 생성합니다. 이 폴더에는 프레임워크의 파일이 포함되어 있으며, 주로 마크다운 및 스크립팅 기반이며 복잡한 독점 형식이 아닙니다.

개발자는 이 폴더를 탐색하여 간단한 구조를 이해하고 '마법' 가정들을 제거하며 프레임워크가 접근 가능하고 투명한 기술을 기반으로 구축되었음을 강화하도록 권장됩니다.

이러한 규칙에는 'grounded only'(환각 세션 없음)와 함수 스케줄링에 중요한 'time aware'가 포함됩니다.

또한 에이전트 안전, HTTP 안전, 설계에 의한 테스트 가능성, 기본적으로 개인 정보 보호 원칙을 강조합니다. 이러한 헌법적 규칙은 모든 AI 생성 코드 및 구성 요소가 엄격한 기업 및 프로젝트 표준을 준수하도록 보장합니다.

이는 전체 개발 프로세스를 관리하는 필수 규칙으로, AI가 미리 정의된 경계 내에서 작동하고 중요한 비즈니스 및 기술 요구 사항에 부합하도록 보장합니다.

이 명령은 AI가 이러한 규칙을 처리하기 시작합니다.

그런 다음 AI는 이러한 원칙을 'memory' 폴더에 통합하여 일관된 마크다운 참조를 만듭니다. 이를 통해 AI의 후속 작업 및 코드 생성이 항상 설정된 기본 규칙에 따라 안내됩니다.

헌법이 확립되면 개발 프로세스는 '사양' 단계로 넘어갑니다. 이 단계는 애플리케이션의 기능적 요구 사항을 정의하고 애플리케이션이 '무엇을' 달성해야 하는지를 개괄적으로 설명하는 데 중점을 둡니다.

기능적 요구 사항에는 데이터 모델링 및 MCP(모델 컨텍스트 프로토콜) 도구 통합과 같은 측면이 포함됩니다. 여기서 강조하는 것은 기술 구현을 자세히 설명하지 않고 원하는 동작과 기능을 명확하게 표현하는 것입니다.

이는 세션 검색 또는 세부 정보 검색을 위한 사용자 스토리와 같이 생성된 모든 사양이 정의된 '필수 사항' 및 원칙에 본질적으로 부합함을 의미합니다.

AI는 프로젝트의 기본 규칙에서 벗어나는 것을 방지하기 위해 이러한 핵심 헌법적 요구 사항을 준수하도록 출력을 적극적으로 수정하고 조정합니다.

이 단계는 기능 사양과 구체적인 구현 사이의 간극을 메웁니다.

여기에는 TypeScript, Node.js, MCP(모델 컨텍스트 프로토콜)와 같은 기술 스택과 HTTP 전송 사용이 포함됩니다. 또한 이 단계는 애플리케이션이 구축되고 배포되는 방식을 설명하는 중요한 배포 및 구성 설정을 다룹니다.

이 상세한 기술 계획은 개발자가 정의된 요구 사항 및 제약 조건에 따라 소프트웨어를 구축하기 위한 명확한 청사진을 갖도록 보장합니다.

기술 계획을 정의할 때 AI가 누락된 종속성 버전을 자동으로 채울 수 있습니다. 이는 편리하지만, 사용자는 이러한 자동 채워진 버전에 유의해야 합니다.

특정 버전이 프로젝트에 필요한 경우 원하는 버전을 명시적으로 명시하는 것이 중요합니다. AI의 기본값이 항상 최신 릴리스 또는 특정 프로젝트 요구 사항과 일치하지 않을 수 있기 때문입니다.

계획 단계 후, 사용자 스토리와 기술 계획을 더 작고 관리하기 쉬운 단위로 분해하기 위해 '/spekit tasks' 명령을 사용합니다. 이 명령은 정의된 모든 요구 사항과 계획을 효율적으로 청크합니다.

이러한 작은 단위는 AI가 쉽게 실행하고 통합하도록 설계되어 개발 프로세스를 간소화합니다. 작업 생성은 헌법, 기능 요구 사항 및 기술 계획을 종합하여 일관된 워크플로우를 보장합니다.

이 분해는 효율적인 AI 처리를 용이하게 하여 모듈식 개발과 원래 사양으로 작업 항목의 더 나은 추적 가능성을 가능하게 합니다.

'spec implement' 명령은 정의된 작업을 실제 소스 코드로 변환하는 다음 중요한 단계입니다. 이 명령은 구조화된 작업을 가져와 해당 애플리케이션 논리를 생성합니다.

결정적으로, 테스트 주도 설계 접근 방식을 적용합니다. 즉, 코드와 함께 테스트가 생성됩니다. 이러한 테스트는 컴파일을 확인하고 개발 작업이 완료되기 전에 생성된 기능이 지정된 요구 사항을 충족하는지 확인합니다.

이 인스펙터는 서버와 직접 상호 작용할 수 있도록 합니다.

데모는 도구 검색 및 세션 실행을 성공적으로 확인하여 생성된 코드가 실제로 기능하며 지정된 요구 사항을 준수함을 보여줍니다. 이 단계는 헌법부터 작동하는 코드까지 전체 개발 파이프라인을 검증합니다.

첫째, 모든 프롬프트를 작성하기 전에 '무엇을' 그리고 '왜'를 포착하는 포괄적인 사양을 항상 작성하여 즉각적인 구현보다 이해를 우선시합니다.

둘째, 협상 불가능한 두세 가지 팀 규칙을 정의하여 '살아있는 헌법'을 수립합니다. 이 문서는 변화하는 프로젝트 표준을 반영하기 위해 정기적으로 검토하고 업데이트해야 합니다.

셋째, 모든 AI 생성 출력에 대한 철저한 검토가 가장 중요합니다. 팀은 통합하기 전에 AI가 생산한 모든 문서와 코드 조각을 신중하게 검토하여 품질과 사양 준수를 보장해야 합니다.