변경 사항 편집 및 반복 작업
변경 사항에 포함된 모든 아티팩트는 언제든지 편집할 수 있는 Markdown 파일입니다. 고정된 "계획 단계"나 승인 게이트, 특별한 편집 모드 같은 것은 없습니다. 구축을 시작한 후 제안서를 변경하고 싶으신가요? proposal.md를 열고 수정하십시오. 구현 도중에 디자인이 잘못되었다는 것을 깨달았나요? design.md를 수정하고 계속 진행하세요. 이것이 전체 답변이며, 이는 의도된 바입니다.
이 페이지는 "잠깐, 되돌아가서 이걸 바꿀 수 있을까?"라고 생각하는 순간을 위한 것입니다. 네, 가능합니다. 일반적인 각 사례별로 방법을 안내해 드립니다.
모든 것을 편집하는 두 가지 방법
항상 두 가지 옵션이 있습니다:
파일을 직접 편집합니다. 아티팩트는
openspec/changes/<name>/에 있는 일반 Markdown 파일입니다. 에디터에서proposal.md,design.md,tasks.md또는specs/아래의 델타 스펙을 열고 변경하십시오. 다른 것은 필요하지 않습니다.AI에게 수정하도록 요청합니다. 채팅창에서 원하는 바를 말하면 됩니다: "캐싱 아이디어를 삭제하고 속도 제한(rate-limit) 섹션을 추가하도록 제안서를 업데이트해 주세요." 또는 "디자인은 폴링이 아닌 큐(queue)를 사용해야 합니다." AI가 변경 사항의 나머지 내용을 컨텍스트로 사용하여 아티팩트를 대신 편집합니다.
상황에 맞는 것을 사용하십시오. 사소한 문구 수정인가요? 파일을 편집하세요. 실질적인 재고찰인가요? 전체 컨텍스트를 가지고 AI에게 수정을 요청하십시오.
"시작한 후에 제안서(또는 스펙)를 어떻게 업데이트하나요?"
그냥 업데이트하면 됩니다. 같은 변경 사항을 다듬은 것입니다.
확장된 명령어를 사용하고 있다면 자연스러운 흐름은 다음과 같습니다: 아티팩트를 편집한 다음, 새로운 상태에서 작업을 이어받기 위해 /opsx:continue를 실행하거나, 업데이트된 계획에 따라 계속 구현하기 위해 /opsx:apply를 실행합니다. 기본 core 명령어를 사용한다면, 아티팩트를 편집하고 /opsx:apply를 실행하십시오. 이는 현재 파일을 읽어들이므로, 아티팩트에 무엇이 적혀 있든 그에 맞춰 구축을 진행합니다.
정신 모델은 다음과 같습니다: 아티팩트는 서명된 계약서가 아니라 실시간 계획입니다. AI는 항상 현재 내용을 기반으로 작동하므로, 이를 편집하는 것이 작업을 유도합니다.
text
You: 이 변경 사항의 접근 방식을 바꾸고 싶습니다.
You: [design.md를 편집하거나, AI에게 지시:]
동기 호출 대신 백그라운드 잡(background job)을 사용하도록 design.md를 업데이트해 주세요.
AI: design.md가 업데이트되었습니다. 작업 목록은 여전히 적합합니다. 계속 적용할까요?
You: /opsx:apply이것은 매우 흔한 질문에 대한 답변입니다: 별도의 "제안서 업데이트" 명령어가 필요하지 않기 때문입니다. 파일 자체가 진실의 원천이며, 이를 편집하는 것(수동으로 하든 AI를 통해 하든)이 곧 업데이트입니다.
"구현 후에 검토하려면 어떻게 해야 하나요?"
당신은 "뒤로 돌아갈" 필요가 없습니다. 왜냐하면 당신은 결코 떠난 적이 없기 때문입니다. 워크플로우는 유동적입니다: 검토, 편집, 구현은 함정에 빠지는 순차적인 단계가 아닙니다.
구체적으로, /opsx:apply 작업을 수행한 후:
- 계획을 다시 살펴보고 싶으신가요? 아티팩트를 열어 읽거나, 터미널에서
openspec show <change>를 실행하여 통합된(consolidated) 보기를 확인하십시오. - 변경할 만한 것을 찾았나요? 아티팩트를 편집하거나 (AI에게 요청), 계속 진행하십시오.
- 코드가 계획과 일치하는지 구조화된 검사를 원하시나요?
/opsx:verify를 실행하십시오(확장 명령어). 이는 어떤 것도 차단하지 않으면서 완전성, 정확성 및 응집력(coherence)을 보고합니다. Workflows: Verify를 참조하십시오.
돌아갈 "검토 단계"는 없습니다. 왜냐하면 검토는 구현 후에도 언제든지 할 수 있는 것이기 때문입니다.
"제가 코드를 수동으로 편집했습니다. 이를 OpenSpec과 어떻게 조화시켜야 하나요?"
이것은 끊임없이 발생하며 괜찮습니다. 에디터에서 무언가를 조정했고, 이제 코드와 아티팩트가 불일치합니다. 어떤 방향이 진실인지에 따라 이들을 다시 동기화하십시오:
- 코드가 올바르고, 스펙이 구식입니다. 실제로 배포한 동작을 설명하도록 델타 스펙(그리고 관련 있다면 태스크)을 업데이트하십시오. 아카이브하기 전에 스펙은 현실과 일치해야 합니다. 왜냐하면 아카이브는 스펙을 진실의 원천에 병합하기 때문입니다.
- 스펙이 올바르고, 코드가 벗어났습니다. 코드가 스펙과 일치할 때까지 계속 구축하거나 수정하십시오.
불일치를 빠르게 파악하는 방법은 /opsx:verify를 사용하는 것입니다. 이는 아티팩트와 코드를 읽고 어디에서 벗어나는지 알려줍니다. 그 출력을 조화(reconciliation)를 위한 할 일 목록으로 간주한 다음, 두 가지가 일치할 때 아카이브하십시오.
원칙은 다음과 같습니다: 아카이브 시점에 스펙이 기록된 진실이 됩니다. 따라서 아카이브하기 전에, 스펙이 코드가 하는 일을 정직하게 반영하도록 만드십시오. 수동 편집은 환영합니다. 단지 그것이 조용히 스펙을 비동기화(desync)시키도록 내버려 두지는 마십시오.
만족스럽지 않은 제안서를 다듬기
생성된 제안서가 목표에 미치지 못한다면, 세 가지 좋은 방법이 있습니다:
- 제자리에 반복합니다. AI에게 무엇이 문제인지 알려주세요 ("범위가 너무 광범위하니 관리자 기능을 삭제해 주세요") 그리고 수정을 요청하십시오. 가장 저렴하고 보통 올바른 방법입니다.
- 먼저 탐색한 다음, 다시 제안합니다. 문제가 아이디어 자체가 불분명하다면,
/opsx:explore로 돌아가서 깊이 생각한 후 더 명확한 제안이 나오도록 하십시오. Explore First를 참조하십시오. - 새롭게 시작합니다. 의도가 근본적으로 변경되었다면, 이전 것을 패치하는 것보다 새로운 변경 사항을 만드는 것이 더 명확할 수 있습니다.
마지막 방법은 별도의 결정 가이드가 있으며, 다음 내용을 참고하십시오.
업데이트 시점과 새 변경 사항 시작 시점
요약: 동일한 작업을 다듬는 경우에 업데이트하고; 의도가 근본적으로 바뀌었거나 범위가 다른 작업으로 폭발했을 때는 새로 시작합니다.
- 목표는 같지만 접근 방식이 더 좋다면? 업데이트하십시오.
- 범위를 좁히는 경우(MVP를 먼저 배포하고, 나머지는 나중에)? 업데이트한 다음 아카이브하고, 두 번째 단계에 대한 새로운 변경 사항을 만드십시오.
- 문제 자체가 바뀐 경우("다크 모드를 추가"가 "전체 테마 시스템 구축"으로 바뀜)? 새 변경 사항입니다.
Workflows: When to Update vs Start Fresh에 전체 순서도와 작업 예시가 있으며, OPSX: When to Update vs. Start Fresh에서 더 깊이 다룹니다.
태스크(Tasks)에 대한 참고 사항
tasks.md는 고정된 계획서가 아니라 살아있는 체크리스트입니다. 구현하면서 발견한 태스크를 추가하거나, 불필요하다고 판명된 것을 제거하거나, 순서를 재배열할 수 있습니다. AI는 /opsx:apply를 수행하는 동안 항목을 완료 처리하며, 나중에 돌아오면 아직 확인되지 않은 첫 번째 태스크부터 작업을 재개합니다. 중간에 목록을 편집하는 것은 예상되는 일입니다.
다음으로 이동할 곳
- Workflows - 패턴 및 업데이트 대 새 시작 결정 가이드
- Explore First - 아이디어를 다시 생각해야 할 때 돌아가야 하는 곳
- Commands -
/opsx:continue,/opsx:apply,/opsx:verify상세 설명 - Concepts: Artifacts - 각 아티팩트의 용도