기존 프로젝트에서 OpenSpec 사용하기

전체 코드베이스를 문서화할 필요는 없습니다. 변경할 부분에 대해서만 스펙을 작성하세요. 이것이 기존 프로젝트에 OpenSpec을 도입하는 데 있어 가장 중요한 단 하나의 사실이며, OpenSpec이 brownfield(기존 시스템) 우선으로 구축된 이유입니다.

흔히 제기되는 우려는 이렇습니다. "제 앱은 80,000줄짜리 레거시입니다. OpenSpec이 유용해지려면 전부 스펙을 작성해야 하나요?" 아닙니다. 저희도 그렇게 하는 것을 싫어합니다. OpenSpec은 한 번에 모든 것을 다루는 것이 아니라, 변경 사항 하나하나를 통해 스펙을 성장시킵니다. 첫 번째 변경 사항으로 해당 부분이 건드려졌다는 것을 문서화하고, 다음 변경 사항으로 그 부분을 문서화하며, 몇 달에 걸쳐 스펙이 실제로 수행하는 작업 주변을 자연스럽게 채워나갑니다.

이 가이드는 '바다를 통째로 끓여내는' 일 없이 첫날부터 시작하는 방법을 보여줍니다.

30초 버전

$ cd your-existing-project
$ openspec init          # openspec/ 및 AI 도구의 명령어를 추가합니다.

그런 다음, AI 채팅에서:

/opsx:explore            # 선택 사항: AI가 당신이 다룰 영역을 읽도록 합니다.
/opsx:propose <실제로 필요로 하는 작고 현실적인 변경 사항>
/opsx:apply
/opsx:archive

이제 스펙은 해당 변경 사항이 건드린 시스템의 부분만을 정확히 설명합니다. 그 이상도 아닙니다. 나머지 80,000줄에 대해 걱정하는 것은 끝입니다.

delta-first가 핵심인 이유

OpenSpec 변경 사항은 ADDED, MODIFIED, REMOVED와 같은 **델타(deltas)**로 작성됩니다. 델타는 전체 시스템이 아닌 현재 동작과 관련하여 무엇이 바뀌고 있는지를 설명합니다.

이는 바로 brownfield 작업에 필요한 것입니다. 당신은 거의 처음부터 무언가를 구축하고 있지 않습니다. 필드를 추가하거나, 리디렉션을 수정하거나, 타임아웃을 조이는 작업을 하고 있습니다. 델타를 사용하면 주변의 모든 것을 담은 40페이지짜리 스펙을 먼저 작성할 필요 없이, 그 한 가지 변경 사항만을 정확하게 지정할 수 있습니다.

따라서 openspec/specs/ 디렉토리는 처음부터 가득 차고 완벽하지 않습니다. 거의 비어 있는 상태로 시작하여 축적됩니다. 각 아카이브된 변경 사항이 자신의 델타를 병합합니다. auth/에 대한 스펙은 여러 개의 인증(auth) 관련 변경 사항을 만든 후에야 철저해지는데, 바로 그때가 그것이 철저해야 하는 시점입니다.

더 깊은 메커니즘을 알고 싶다면 Concepts: Delta Specs를 참조하십시오.

실제 코드베이스에서의 첫 번째 변경 사항

작고 현실적인 무언가를 고르십시오. 장난감이나 재작성(rewrite)이 아닙니다. 이번 주에 원래 할 예정이었던 변경 사항이어야 합니다. 작은 초기 변경 사항은 낮은 위험 부담으로 워크플로우를 가르쳐 줍니다.

1단계: AI가 관련 영역을 읽도록 하세요. 이것이 /opsx:explore가 익숙하지 않거나 큰 코드베이스에서 제 역할을 하는 부분입니다. 다루려고 하는 부분을 지정하고, 무언가를 제안하기 전에 어떻게 작동하는지 매핑하도록 하십시오.

You: /opsx:explore

AI:  무엇을 탐색하시겠습니까?

You: 공개 API에 속도 제한(rate limiting)을 추가해야 하는데, 요청이 미들웨어(middleware)를 통해 현재 어떻게 흐르는지 잘 모르겠습니다.

AI:  제가 추적해 보겠습니다... [라우터, 미들웨어 스택 및 구성을 읽음]
     요청은 Express에 도달하고 인증 미들웨어를 거쳐 컨트롤러로 전달됩니다. 오늘날 속도 제한 레이어는 없습니다. 가장 깔끔한 삽입 지점은 인증 직후의 미들웨어입니다. 제가 범위를 설정해 드릴까요?

AI가 이제 실제 구조를 이해한다는 점에 주목하십시오. 따라서 AI가 작성하는 제안은 일반적인 템플릿이 아니라 당신의 코드에 맞게 들어맞을 것입니다. 큰 코드베이스에서 이 단 하나의 습관이 가장 많은 고통을 줄여줍니다. Explore First를 참조하십시오.

2단계: 변경 사항을 제안합니다. 제안과 그 델타 스펙은 오직 이 변경 사항만을 담습니다.

You: /opsx:propose add-api-rate-limiting

3단계: /opsx:apply와 /opsx:archive를 사용하여 빌드하고 아카이브합니다. 이는 모든 변경 사항과 동일합니다. 아카이브 후, 당신이 어차피 필요했던 변경 사항에서 태어난 속도 제한 동작에 대한 실제 스펙을 갖게 됩니다.

가이드 투어를 선호하시나요? onboard를 사용하세요

만약 내러레이션(narration)과 함께 전체 루프가 자신의 코드에서 일어나는 것을 보고 싶다면, 확장된 명령어인 /opsx:onboard가 정확히 그것을 수행합니다. 즉, 작은 안전한 개선 사항에 대해 코드베이스를 스캔한 다음, 제안하고, 빌드하고, 아카이브하는 과정을 설명하며 당신을 안내합니다.

먼저 확장된 명령어를 켜십시오:

$ openspec config profile      # 확장된 워크플로우를 선택합니다.
$ openspec update              # 이 프로젝트에 적용합니다.

그런 다음 채팅에서:

/opsx:onboard

이는 실제 프로젝트에 대한 가장 온화한 소개이며, 당신에게 유지하거나 폐기할 수 있는 진정한 (작은) 변경 사항을 남깁니다. Commands: /opsx:onboard를 참조하십시오.

"하지만 이미 요구사항 문서를 가지고 있습니다"

PRD(제품 요구사항 정의서), SRS(소프트웨어 요구사항 명세서), 공식 스펙, 심지어 TLA+ 모델을 가지고 있을 수도 있습니다. 좋습니다. 그것들을 통째로 가져오지도, 버리지도 마십시오.

기존 문서는 변환해야 할 스펙이 아니라 탐색을 위한 소스 자료로 취급하십시오. 변경 사항을 시작할 때, AI에게 관련 섹션을 붙여넣거나 지정하고, 거기서 집중된 OpenSpec 델타를 만들도록 하십시오. 이 델타는 현재 당신이 바꾸고 있는 동작을 OpenSpec의 테스트 가능한 요구사항 및 시나리오 형태로 포착합니다. 원래 문서는 배경 자료로 그대로 유지됩니다.

솔직한 이유는 다음과 같습니다: OpenSpec 스펙은 의도적으로 행동(behavior) 우선이며 변경 사항에 맞춰져 있습니다. 40페이지짜리 PRD는 다른 임무를 가진 다른 산출물입니다. 일회성 대량 변환을 강요하면 아무도 신뢰하지 않는 크고 오래된 스펙이 나올 가능성이 높습니다. 실제 변경 사항으로부터 스펙을 성장시키도록 하는 것이 정확성을 유지하게 합니다.

You: /opsx:explore
You: 여기 저희 PRD의 체크아웃에 대한 섹션입니다. 저는 다음으로 "게스트 체크아웃" 요구사항을 구현할 예정입니다.
     [관련 요구사항 붙여넣기]
AI:  [읽고, 명확히 하는 질문을 던진 후, 변경 사항 범위를 설정하는 것을 도움]
You: /opsx:propose add-guest-checkout

대규모 코드베이스에서 스펙 정리하기

스펙은 openspec/specs/ 아래에 존재하며, **도메인(domain)**별로 그룹화됩니다. 도메인은 팀이 시스템을 생각하는 방식과 일치하는 논리적인 영역입니다. 처음부터 전체 분류 체계를 설계할 필요는 없습니다. 해당 영역에서 첫 번째 변경 사항이 발생했을 때 도메인 폴더를 생성하십시오.

도메인을 분할하는 일반적인 방법:

• 기능 영역별: auth/, payments/, search/
• 컴포넌트별: api/, frontend/, workers/
• 경계 컨텍스트(bounded context)별: ordering/, fulfillment/, inventory/

새로운 사람이 고개를 끄덕일 만한 것을 선택하십시오. 나중에 다듬을 수 있습니다. Concepts: Specs를 참조하십시오.

모노레포 및 여러 리포지토리를 아우르는 작업

모노레포의 경우, 가장 간단한 모델은 리포지토리 루트에 하나의 openspec/ 디렉토리를 두고, 도메인이 패키지나 서비스와 매핑되는 것입니다. 이것으로 대부분의 팀을 커버할 수 있습니다.

만약 당신의 작업이 여러 개의 리포지토리 (또는 별개의 것으로 취급하는 여러 패키지)를 진정으로 아우른다면, OpenSpec은 베타 기능인 stores를 제공합니다. 계획(planning)이 코드 리포지토리 중 하나 안에 존재할 필요가 없도록, 모든 코드 리포지토리가 참조할 수 있는 독립적인 스탠드얼론(standalone) 리포지토리에 계획을 보관하는 것입니다. 이는 베타 버전이므로 명령어와 상태를 진화하는 것으로 간주하십시오. 정신적 모델과 가장 유용한 경로에 대해서는 Stores User Guide로 시작하십시오.

몇 가지 솔직한 주의사항

• 모든 것을 백필(back-fill)하려는 충동을 억제하세요. 변경하고 있지 않은 코드에 대해 스펙을 작성하는 것은 생산적으로 느껴지지만, 대개 그렇지 않습니다. 그러한 스펙은 현실을 추적하도록 강제하는 것이 없기 때문에 오래됩니다. 실제 변경 사항이 당신의 스펙을 이끌도록 하십시오.
• 초기 변경 사항은 작게 유지하세요. 처음 몇 번의 변경 사항은 배포만큼이나 리듬을 배우는 것에 관한 것입니다. 좁은 범위는 빠른 루프와 저렴한 교훈을 만듭니다.
• openspec/을 git에 커밋하십시오. 당신의 스펙과 아카이브는 그것이 설명하는 코드와 함께 버전 관리 시스템에 속해야 합니다.
• AI에게 컨텍스트를 제공하세요. 강력한 관례(convention)를 가진 대규모 코드베이스에서는, 모든 제안이 당신의 스택과 패턴을 존중하도록 openspec/config.yaml의 context:를 채우십시오. Customization을 참조하십시오.

다음으로 나아갈 곳

• Explore First - 변경하기 전에 코드를 이해하는 핵심 습관
• Getting Started - 전체 첫 번째 변경 사항 워크스루(walkthrough)
• Editing & Iterating on a Change - 배우면서 변경 사항 조정하기
• Concepts: Delta Specs - 델타가 brownfield 작업을 깨끗하게 만드는 이유
• Customization - OpenSpec에게 프로젝트의 관례를 가르치기