팀에서 OpenSpec 사용하기

다른 안내서의 모든 내용은 혼자 작업하든 20명 규모의 팀에서 작업하든 동일하게 적용됩니다. 팀에서는 사양을 어디에 둘지, 팀원이 계획을 어떻게 검토할지, 기존 풀 리퀘스트 흐름에 이를 어떻게 맞출지와 같은 주변 질문이 추가됩니다.

간단히 답하면 변경 사항은 파일일 뿐이며 OpenSpec은 git을 건드리지 않습니다. 따라서 기존 워크플로를 대체하는 대신 그 안에 자연스럽게 들어갑니다. 이 페이지에서는 잘 작동하는 관례를 설명합니다.

한 가지 원칙: OpenSpec은 git을 건드리지 않습니다

OpenSpec은 openspec/ 아래의 일반 Markdown 파일을 읽고 씁니다. 프로젝트에서 커밋, 브랜치 생성, 푸시, 풀을 하지 않으며, store를 직접 복제하거나 동기화하지도 않습니다. 즉:

• openspec/도 다른 소스와 함께 커밋합니다. 사양, 진행 중인 변경 사항, 보관 기록은 프로젝트 이력의 일부입니다. (네, 폴더 전체를 커밋하세요. FAQ를 참조하세요.)
• 변경 사항도 코드처럼 버전 관리하는 폴더입니다. openspec/changes/add-dark-mode/는 브랜치에 있는 파일일 뿐입니다.
• 아래 내용은 강제가 아니라 관례입니다. OpenSpec은 이 방식을 강요하지 않으며, 기존 흐름에 잘 맞도록 안내할 뿐입니다.

일상적인 작업 흐름

효과적인 워크플로는 변경 사항을 브랜치와 풀 리퀘스트에 연결합니다.

git switch -c add-dark-mode        start a branch, as usual
   │
/opsx:propose add-dark-mode        계획 초안 작성(제안 + 사양 + 작업)
   │
REVIEW THE PLAN                    you read it before any code — see Reviewing a Change
   │
/opsx:apply                        build it; artifacts + code change together
   │
git commit && open a PR            the PR contains the spec delta AND the code
   │
teammate reviews, merges
   │
/opsx:archive                      fold the delta into specs/, move the change to archive/

계획과 코드는 같은 브랜치에 나란히 있으므로 팀원들이 둘을 함께 검토할 수 있습니다. 6개월 뒤에도 보관된 사양을 통해 코드가 현재 모습인 이유를 확인할 수 있습니다.

풀 리퀘스트에서 사양 검토하기

팀에서 OpenSpec의 이점을 가장 크게 느끼는 부분입니다. PR에 변경 사항의 델타 사양이 포함되면 검토자는 코드 한 줄을 읽기도 전에 일반 언어로 작성된 이 변경 사항이 수행해야 할 작업에 대한 설명을 확인할 수 있습니다. 일반 diff만으로는 얻기 어려운 정보입니다.

검토자는 다음 순서로 살펴보는 것이 좋습니다.

1. proposal.md를 읽습니다. 올바른 문제와 범위를 다루나요?
2. specs/ 아래의 델타를 읽습니다. “완료”의 정의가 올바른가요? PR에서 진행하는 변경 사항 검토의 2분 점검입니다.
3. 그다음 코드 diff를 읽습니다. 명시된 요구 사항을 정확히 구현했나요?

접근 방식에 동의하지 않는 검토자는 코드 300줄을 두고 다시 논쟁하는 대신 제안에 대해 간단히 의견을 남길 수 있습니다. 검토자가 먼저 델타 사양을 보도록 PR 설명 상단에 배치하거나 변경 사항 폴더를 안내하세요.

보관 시점

보관하면 변경 사항의 델타가 기본 openspec/specs/에 반영되고 변경 사항 폴더는 openspec/changes/archive/YYYY-MM-DD-<name>/으로 이동합니다. specs/는 공유 기준 정보이므로 팀에서는 시점이 중요합니다. 다음 두 가지 관례가 있습니다.

• PR 병합 후 보관(권장). 브랜치에서 변경 사항을 진행하다가 기본 브랜치에 병합된 후 그곳에서 보관합니다(보통 작은 후속 커밋이나 정기 정리 작업으로 처리). 실제로 배포된 작업만 공유 specs/에 반영할 수 있습니다.
• PR 안에서 보관. 소규모 팀에 더 간단한 방법입니다. 코드 추가와 같은 PR에서 동기화하고 보관합니다. 대신 specs/ diff와 코드 diff가 함께 들어가 PR이 복잡해질 수 있습니다.

둘 중 하나를 정해 일관되게 따르세요. 어떤 방식을 선택하든 /opsx:archive는 작업이 완료됐는지 확인하고 먼저 동기화할지 제안하므로 미완성 내용이 실수로 병합되는 일을 막습니다.

두 사람이 변경 사항을 병렬로 작업하기

변경 사항은 서로 다른 폴더에 저장되므로 충돌하지 않습니다.

• 서로 다른 사람이 서로 다른 변경 사항을 작업하면 문제없습니다. add-dark-mode와 rate-limit-login은 서로 다른 브랜치의 다른 폴더에 있으므로 둘 다 보관되기 전까지 서로 영향을 주지 않습니다.
• 변경 사항 하나에는 담당자 한 명을 둡니다. 두 사람이 같은 변경 사항 폴더를 편집하면 같은 파일을 함께 편집할 때처럼 충돌합니다. 변경 사항의 작성자를 한 명으로 제한하거나 둘로 나누세요(변경 사항 규모 조정의 또 다른 이유입니다).
• 충돌이 생길 수 있는 곳은 specs/입니다. 두 변경 사항이 같은 요구 사항을 수정하면 두 번째 변경 사항을 보관할 때 openspec/specs/…/spec.md에서 충돌할 수 있습니다. 다른 병합 충돌처럼 실제 동작을 반영하는 요구 사항을 남겨 해결하세요. 드문 일이지만 유용한 기능입니다. git이 두 변경 사항의 시스템 동작에 대한 의견이 다르다고 알려 주는 것입니다.

계획이 단일 저장소의 범위를 넘어설 때

앞선 내용은 모두 코드 저장소 자체의 openspec/ 폴더에 계획이 저장된다고 가정하며, 이것이 기본적으로 올바른 방식입니다. 계획이 여러 저장소나 팀에 걸치는 경우(예: 하나의 기능이 세 서비스를 건드리거나 한 팀이 소유한 요구 사항을 다른 팀이 사용하는 경우)에는 베타 stores 기능을 사용할 수 있습니다. 계획을 전용 저장소에 두고 각 코드 저장소에서 참조합니다. Stores 사용자 안내서부터 살펴보세요.

다음 단계

• 변경 사항 검토 — PR 안에서 진행하는 검토 단계
• 좋은 사양 작성하기 — 하나의 브랜치에 들어맞도록 변경 사항의 규모를 조정하는 방법 포함
• Stores 사용자 안내서 — 저장소와 팀을 아우르는 계획