변경 사항 편집 및 반복하기
변경 사항의 모든 아티팩트는 언제든지 편집할 수 있는 마크다운 파일일 뿐입니다. 잠긴 '기획 단계'도, 승인 게이트도, 진입해야 할 특별 편집 모드도 없습니다. 빌드를 시작한 후 제안을 변경하고 싶으신가요? proposal.md를 열어 수정하세요. 구현 중간에 디자인이 잘못된 것을 발견했나요? design.md를 수정하고 계속 진행하세요. 이것이 전부이며, 의도적으로 그렇게 설계된 것입니다.
이 페이지는 '잠깐, 그거 다시 바꿀 수 있나?' 라고 생각하는 순간을 위한 것입니다. 네, 가능합니다. 각 일반적인 경우에 대한 방법을 아래에 설명합니다.
모든 것을 편집하는 두 가지 방법
항상 두 가지 방법을 사용할 수 있습니다:
파일을 직접 편집하세요. 아티팩트는
openspec/changes/<name>/에 있는 일반 마크다운 파일입니다. 편집기에서proposal.md,design.md,tasks.md, 또는specs/아래의 델타 스펙을 열어 수정하세요. 추가로 필요한 작업은 없습니다.AI에게 수정을 요청하세요. 채팅에서 원하는 내용을 그대로 말하면 됩니다: "캐싱 아이디어를 제거하고 속도 제한 섹션을 추가하도록 제안을 업데이트해줘", 또는 "디자인은 폴링 대신 큐를 사용해야 해" 라고 말하세요. AI는 변경 사항의 나머지 부분을 컨텍스트로 사용하여 아티팩트를 편집해줍니다.
상황에 맞는 방법을 사용하세요. 작은 문구 수정? 파일을 직접 편집하세요. 근본적인 재고려? AI가 전체 컨텍스트로 수정하도록 하세요.
"빌드를 시작한 후 제안(또는 스펙)을 어떻게 업데이트하나요?"
그냥 업데이트하세요. 동일한 변경 사항을 다듬는 것일 뿐입니다.
확장 명령어를 사용 중이라면 자연스러운 흐름은 다음과 같습니다: 아티팩트를 편집한 후 /opsx:continue를 실행하여 새 상태에서 이어하거나, /opsx:apply를 실행하여 업데이트된 계획에 맞춰 구현을 계속하세요. 기본 core 명령어를 사용 중이라면 아티팩트를 편집한 후 /opsx:apply를 실행하세요. 이 명령어는 현재 파일을 읽기 때문에 아티팩트에 적힌 내용을 기준으로 빌드합니다.
핵심 개념: 아티팩트는 서명된 계약이 아니라 실시간 계획입니다. AI는 항상 아티팩트의 현재 내용을 기준으로 작업하기 때문에, 아티팩트를 편집하면 작업의 방향을 조정할 수 있습니다.
text
사용자: 이 변경 사항의 접근 방식을 바꾸고 싶어요.
사용자: [design.md를 편집하거나, AI에게 다음과 같이 말하세요:]
design.md를 동기 호출 대신 백그라운드 잡을 사용하도록 업데이트해줘.
AI: design.md를 업데이트했어요. 작업 목록은 그대로 적합한데, 계속 적용해볼까요?
사용자: /opsx:apply이는 매우 흔한 질문에 대한 답입니다: 별도의 '제안 업데이트' 명령어가 없는 것은 그런 명령어가 필요하지 않기 때문입니다. 파일이 진실의 원천(source of truth)이며, 파일을 편집하는 것(직접 하거나 AI를 통해)이 곧 업데이트입니다.
"구현 후 리뷰를 하려면 어떻게 돌아가나요?"
돌아갈 필요가 없습니다. 왜냐하면 리뷰 단계에서 벗어난 적이 없기 때문입니다. 워크플로우는 유동적입니다: 리뷰, 편집, 구현은 당신이 갇히는 순차적인 단계가 아닙니다.
구체적으로, 일부 /opsx:apply 작업을 수행한 후:
- 계획을 다시 검토하고 싶으신가요? 아티팩트를 열어 읽거나, 터미널에서
openspec show <change>를 실행하여 통합된 보기를 확인하세요. - 변경할 내용을 발견했나요? 아티팩트를 편집하거나(혹은 AI에게 요청하세요) 편집한 후 계속 진행하세요.
- 코드가 계획과 일치하는지 구조화된 검사를 원하시나요?
/opsx:verify(확장 명령어)를 실행하세요. 이 명령어는 완전성, 정확성, 일관성을 보고하며 어떤 작업도 차단하지 않습니다. 자세한 내용은 워크플로우: 검증을 참고하세요.
돌아갈 '리뷰 단계'가 없습니다. 리뷰는 구현 후를 포함한 어느 시점에서나 할 수 있는 작업이기 때문입니다.
"코드를 직접 편집했어요. OpenSpec과 어떻게 맞춰야 하나요?"
이는 매우 흔하게 발생하는 일이며 괜찮습니다. 편집기에서 무언가를 수정한 후 코드와 아티팩트가 일치하지 않게 될 수 있습니다. 진실에 맞는 방향으로 다시 동기화하세요:
- 이제 코드가 정확하고 스펙이 구식입니다. 실제로 출시한 동작을 설명하도록 델타 스펙(및 관련된 경우 작업 목록)을 업데이트하세요. 아카이빙하면 스펙이 진실의 원천에 병합되기 때문에, 아카이빙하기 전에 스펙이 실제와 일치하도록 하세요.
- 스펙이 정확하고 코드가 빗나갔습니다. 코드가 스펙과 일치할 때까지 빌드하거나 수정을 계속하세요.
불일치를 빠르게 찾는 방법은 /opsx:verify를 실행하는 것입니다: 이 명령어는 아티팩트와 코드를 읽어 불일치하는 부분을 알려줍니다. 출력 결과를 조정할 할 일 목록으로 간주한 후, 일치하면 아카이빙하세요.
원칙: 아카이빙 시점에 스펙이 기록상의 진실이 됩니다. 따라서 아카이빙하기 전에 스펙이 코드가 수행하는 작업을 정직하게 반영하도록 하세요. 수동 편집은 환영하지만, 스펙이 조용히 동기화되지 않도록 하세요.
만족스럽지 않은 제안 다듬기
생성된 제안이 목표에 미치지 못한다면, 세 가지 좋은 방법이 있습니다:
- 제자리에서 반복하세요. AI에게 무엇이 잘못되었는지 말해주세요("범위가 너무 넓어요, 관리자 기능을 제거해줘") 그리고 수정하도록 하세요. 가장 저렴하고 보통 올바른 방법입니다.
- 먼저 탐색한 후 재제안하세요. 문제가 아이디어 자체가 불분명한 것이라면,
/opsx:explore로 돌아가 생각을 정리한 후 더 명확한 제안이 나오도록 하세요. 먼저 탐색하기를 참고하세요. - 새로 시작하세요. 의도가 근본적으로 변경된 경우, 기존 것을 패치하는 것보다 새로운 변경 사항을 만드는 것이 더 명확할 수 있습니다.
마지막 방법에 대한 결정 가이드는 아래에 있습니다.
업데이트할지 새 변경 사항을 시작할지 결정하기
간단히 말해: 같은 작업을 다듬는 것이라면 업데이트하고, 의도가 근본적으로 변경되었거나 범위가 완전히 다른 작업으로 확장된 경우 새로 시작하세요.
- 동일한 목표, 더 나은 접근 방식? 업데이트하세요.
- 범위 축소(지금 MVP를 출시하고 나중에 추가)? 업데이트한 후 아카이빙하고, 2단계를 위한 새 변경 사항을 만드세요.
- 문제 자체가 변경된 경우("다크 모드 추가"가 "전체 테마 시스템 구축"으로 바뀜)? 새 변경 사항을 만드세요.
전체 플로우차트와 실습 예제는 워크플로우: 업데이트 vs 새로 시작 결정하기에서 확인할 수 있으며, 더 자세한 내용은 OPSX: 업데이트 vs 새로 시작에서 다루고 있습니다.
작업에 대한 참고 사항
tasks.md는 동적으로 변경되는 체크리스트이며, 고정된 계획이 아닙니다. 구현하는 동안 발견한 작업을 추가하거나, 불필요한 것으로 판명된 작업을 제거하거나 순서를 바꿀 수 있습니다. AI는 /opsx:apply를 실행하는 동안 완료한 항목에 체크 표시를 하며, 나중에 돌아오면 체크되지 않은 첫 번째 항목부터 다시 시작합니다. 작업 중간에 목록을 편집하는 것은 예상된 동작입니다.