팀에서의 OpenSpec
다른 가이드의 모든 내용은 혼자 작업하든 20명 규모의 팀에서 작업하든 동일하게 적용됩니다. 팀에서 달라지는 부분은 주변의 몇 가지 질문들뿐입니다: 명세는 어디에 저장해야 하고, 팀원들은 계획을 어떻게 검토해야 하며, 기존에 사용하던 풀 리퀘스트 흐름과 어떻게 연동할 수 있을까요?
짧은 답변은 다음과 같습니다: 변경 사항은 단순한 파일일 뿐이며, OpenSpec은 절대 git과 직접 상호작용하지 않습니다. 따라서 기존 워크플로우를 대체하는 대신 자연스럽게 연동됩니다. 이 페이지에서는 효과적으로 작동하는 규약을 설명합니다.
유일한 규칙: OpenSpec은 git과 상호작용하지 않습니다
OpenSpec은 openspec/ 디렉터리 아래에 있는 일반 마크다운 파일만 읽고 씁니다. 프로젝트에서 커밋, 브랜치 생성, 푸시, 풀 작업을 직접 수행하지도 않고, 자체적으로 스토어를 복제하거나 동기화하지도 않습니다. 즉 다음을 의미합니다:
openspec/디렉터리를 일반 소스 코드처럼 커밋하세요. 명세, 진행 중인 변경 사항, 아카이브는 프로젝트 기록의 일부입니다. (네, 전체 폴더를 커밋하세요. FAQ를 참고하세요.)- 변경 사항은 코드처럼 버전 관리하는 폴더입니다.
openspec/changes/add-dark-mode/는 브랜치에 있는 단순한 파일에 불과합니다. - 아래의 모든 내용은 강제 규칙이 아닌 규약입니다. OpenSpec이 이 방식을 따르도록 강제하지는 않습니다. 다만 이 방식이 가장 자연스럽게 연동되기 때문입니다.
일상적인 워크플로우
잘 작동하는 워크플로우는 변경 사항을 브랜치와 풀 리퀘스트에 매핑하는 방식입니다:
git switch -c add-dark-mode 평소처럼 브랜치를 생성합니다
│
/opsx:propose add-dark-mode 계획 초안 작성 (제안서 + 명세 + 작업 목록)
│
계획 검토 코드 작성 전에 내용을 읽어보세요 — 변경 사항 검토하기 참고
│
/opsx:apply 빌드 및 구현; 산출물과 코드 변경을 함께 진행합니다
│
git commit && PR 열기 PR에는 명세 변경분과 코드가 모두 포함됩니다
│
팀원 검토 후 병합
│
/opsx:archive 변경분을 specs/에 통합하고, 변경 폴더를 아카이브로 이동합니다계획과 코드는 같은 브랜치에 나란히 존재하므로, 팀원들이 두 가지를 함께 검토할 수 있습니다. 6개월 후 아카이브된 명세를 봐도 코드가 현재와 같은 형태를 갖게 된 이유를 명확히 확인할 수 있습니다.
풀 리퀘스트에서 명세 검토하기
이 부분이 팀이 효과를 느끼는 지점입니다. PR에 변경 사항의 명세 변경분이 포함되어 있으면, 검토자는 코드 한 줄을 읽기 전에 원시 diff로는 결코 얻을 수 없는 것을 확인할 수 있습니다: 이 변경 사항이 수행해야 할 작업에 대한 평범한 언어로 작성된 설명이죠.
검토자가 따라야 할 좋은 검토 순서는 다음과 같습니다:
proposal.md읽기 — 올바른 문제와 범위를 다루고 있나요?specs/아래의 변경분 읽기 — "완료"가 올바르게 정의되어 있나요? (이는 변경 사항 검토하기의 2분 검토 과정이 PR 내에서 진행되는 것입니다.)- 그 다음 코드 diff 읽기 — 요구사항을 정확히 충족하고 있나요?
접근 방식에 동의하지 않는 검토자는 300줄이 넘는 코드 전반에 걸쳐 재논의하는 대신, 제안서에 의견을 남기는 것만으로도 저렴한 비용으로 의견을 전달할 수 있습니다. PR 설명 상단에 명세 변경분을 넣거나 검토자에게 변경 폴더를 안내하여, 그곳에서부터 검토를 시작하도록 하세요.
아카이빙 시점
아카이빙은 변경 사항의 변경분을 메인 openspec/specs/에 통합하고, 변경 폴더를 openspec/changes/archive/YYYY-MM-DD-<name>/로 이동하는 작업입니다. specs/는 공유 진실 소스이므로 팀에서 작업할 때는 아카이빙 시점이 중요합니다. 실용적으로 사용할 수 있는 두 가지 규약이 있습니다:
- PR 병합 후 아카이빙 (권장). 브랜치에 진행 중인 변경 사항이 포함되어 있다가 메인 브랜치에 병합된 후 아카이빙을 진행합니다 (대부분 작은 후속 커밋이나 예약된 정리 작업으로 처리합니다). 이렇게 하면 실제로 출시된 작업만 공유
specs/에 반영되므로 일관성을 유지할 수 있습니다. - PR 내부에서 아카이빙. 소규모 팀에 더 간편한 방식입니다: 코드를 추가하는 동일한 PR에서 동기화와 아카이빙을 모두 처리합니다. 다만
specs/변경분과 코드 변경분이 함께 병합되므로 PR이 더 복잡해질 수 있다는 tradeoff가 있습니다.
한 가지 방식을 선택하고 일관되게 적용하세요. 어떤 방식을 선택하든 /opsx:archive는 작업이 완료되었는지 확인한 후 먼저 동기화할지 제안하므로, 실수로 미완료 상태의 내용이 병합되는 일을 방지할 수 있습니다.
두 사람이 동시에 변경 작업하는 경우
변경 사항이 별도의 폴더로 분리되어 있으므로 충돌이 발생하지 않습니다:
- 서로 다른 변경 사항을 다른 사람이 작업하는 경우 — 문제가 없습니다.
add-dark-mode와rate-limit-login은 서로 다른 브랜치에 있는 별도의 폴더이므로, 두 변경 사항이 모두 아카이빙되기 전까지는 서로 영향을 주지 않습니다. - 하나의 변경 사항은 한 명의 소유자가 가집니다. 두 사람이 같은 변경 폴더를 편집하면 두 사람이 같은 파일을 편집할 때와 똑같이 충돌이 발생합니다. 변경 사항을 한 명의 작성자만 담당하도록 하거나, 두 개의 변경 사항으로 분할하세요 (변경 사항의 적정 크기 유지와 관련된 또 다른 이유입니다.)
- 충돌이 발생하는 유일한 위치는
specs/입니다. 두 개의 변경 사항이 모두 동일한 요구사항을 수정하는 경우, 두 번째 변경 사항을 아카이빙할 때openspec/specs/…/spec.md에서 충돌이 발생합니다. 일반적인 병합 충돌처럼 해결하면 되며, 실제 상황을 반영하는 요구사항을 유지하세요. 이런 경우는 드물지만, 이는 기능입니다: git이 두 변경 사항이 시스템이 작동해야 하는 방식에 대해 의견이 달랐다는 것을 알려주는 것이죠.
계획이 하나의 저장소로 감당하기 어려워질 때
위의 모든 내용은 계획이 코드 저장소 자체의 openspec/ 폴더에 존재한다는 가정 하에 작성된 것으로, 이는 기본적으로 올바른 설정입니다. 계획이 여러 저장소나 팀에 걸쳐 실제로 분산되어 있는 경우 (예: 하나의 기능이 세 가지 서비스에 걸쳐 있거나, 한 팀이 소유한 요구사항을 다른 팀이 사용하는 경우) 베타 버전의 스토어 기능이 이에 대응하기 위해 존재합니다: 계획을 별도의 저장소로 분리하여, 모든 코드 저장소가 이 저장소를 참조할 수 있게 하는 기능입니다. 스토어 사용자 가이드부터 시작하세요.
다음으로 확인할 내용
- 변경 사항 검토하기 — 이제 PR 내에서 진행되는 검토 과정입니다.
- 좋은 명세 작성하기 — 변경 사항이 하나의 브랜치에 맞도록 적정 크기로 만드는 방법을 포함합니다.
- 스토어 사용자 가이드 — 저장소와 팀에 걸친 계획 수립 방법을 다룹니다.