AI 코딩 어시스턴트와 코드 작성 전 합의점을 문서로 남기는 방법
어떤 기능을 만들지 고민하다가 AI에게 바로 코드를 짜라고 지시하면, 예상치 못한 결과물이 나올 수 있습니다. 이 도구는 코드 한 줄 쓰기 전에 요구사항과 설계안을 마크다운 파일로 정리해 두어, 사람과 AI가 같은 방향을 보게 합니다. OpenSpec은 AI 코딩 어시스턴트가 읽을 수 있는 명세 스펙을 프로젝트에 추가하는 도구입니다.
명세 기반 개발의 흐름
OpenSpec은 개발 과정을 탐색, 제안, 적용, 아카이브의 네 단계로 나눕니다. 먼저 /opsx:explore 명령어로 아이디어를 탐색하며, AI가 현재 코드베이스를 분석해 최적의 접근법을 제안합니다. 다음으로 /opsx:propose를 사용하면 변경 사항 폴더가 생성되고, 제안서, 요구사항 명세, 기술 설계, 작업 목록이 마크다운 파일로 작성됩니다. 이 단계에서 개발자는 AI가 작성한 계획을 검토하고 수정할 수 있습니다. 최종적으로 /opsx:apply를 실행하면 AI가 작업 목록에 따라 코드를 구현하고, 완료된 변경 사항은 /opsx:archive로 아카이브에 보관됩니다.
팀 단위 계획 공유
개인 프로젝트뿐 아니라 팀 환경에서도 이 도구는 유용합니다. 여러 저장소에 걸친 기능을 개발할 때, 계획은 별도의 저장소인 '스토어'에 보관됩니다. 이 스토어는 git push를 통해 팀 전체와 모든 AI 에이전트가 읽을 수 있는 단일 진실 공급원이 됩니다. 플랫폼 팀이 요구사항 명세를 소유하고, 제품 팀은 읽기 전용으로 참조할 수 있어 위키 문서가 흩어지는 문제를 방지합니다. 현재 스토어 기능은 베타 단계이므로, 가이드를 참고하여 시작하는 것이 좋습니다.
설치 및 초기 설정
OpenSpec를 사용하려면 Node.js 20.19.0 이상의 버전이 필요합니다. macOS나 Linux에서는 Homebrew를 통해 설치할 수 있으며, brew install openspec 명령을 실행하면 됩니다. npm을 사용하는 경우 npm install -g @fission-ai/openspec@latest를 실행합니다. 이 과정은 AI 코딩 어시스턴트에게 설치를 위임할 수도 있으며, 지원되는 30개 이상의 도구 중 하나를 선택하면 해당 도구에 맞는 슬래시 명령 형식이 자동으로 설정됩니다.
사용 전 확인 사항
이 도구는 추론 능력이 높은 모델과 함께 사용할 때 가장 좋은 결과를 냅니다. README에서는 Codex 5.5와 Opus 4.7을 계획 수립 및 구현 모두에 권장합니다. 또한 구현을 시작하기 전에 컨텍스트 윈도우를 정리하는 것이 중요하며, 세션 동안 컨텍스트 위생을 유지해야 합니다. OpenSpec는 익명 사용 통계를 수집하지만, 명령 이름과 버전만 기록하며 인적 정보나 파일 내용은 수집하지 않습니다. CI 환경에서는 자동으로 비활성화되며, 원할 경우 설정 파일이나 환경 변수를 통해 수동으로 비활성화할 수 있습니다. 라이선스는 MIT이며, 기여 시에는 새로운 기능이나 구조 변경 전에 OpenSpec 변경 제안서를 먼저 작성해야 합니다.
