변경 사항 편집 및 반복 개선

변경 사항의 모든 산출물은 언제든 편집할 수 있는 Markdown 파일입니다. 잠겨 있는 “계획 단계”도, 승인 관문도, 별도의 편집 모드도 없습니다. 구현을 시작한 뒤 제안 내용을 바꾸고 싶나요? proposal.md를 열어 수정하면 됩니다. 구현 도중 설계가 잘못됐다는 걸 알게 됐나요? design.md를 고치고 계속 진행하세요. 이것이 전부이며, 의도된 동작입니다.

이 페이지는 “잠깐, 이전으로 돌아가서 바꿀 수 있나?“라는 생각이 들 때를 위한 안내입니다. 물론 가능합니다. 흔히 발생하는 경우별 방법을 살펴보겠습니다.

무엇이든 편집하는 두 가지 방법

항상 다음 두 방법을 모두 사용할 수 있습니다.

1. 파일을 직접 편집합니다. 산출물은 openspec/changes/<name>/ 아래에 있는 일반 Markdown 파일입니다. 편집기에서 proposal.md, design.md, tasks.md 또는 specs/ 아래의 델타 사양을 열어 수정하면 됩니다. 다른 작업은 필요하지 않습니다.

2. AI에게 수정을 요청합니다. 채팅에서 원하는 내용을 말하면 됩니다. 예를 들어 “캐싱 아이디어를 빼고 속도 제한 섹션을 추가하도록 제안을 수정해 줘” 또는 “폴링 대신 큐를 사용하도록 설계를 바꿔 줘”라고 요청하세요. AI가 변경 사항의 나머지 내용을 맥락으로 삼아 산출물을 편집합니다.

상황에 맞는 방법을 사용하세요. 표현만 조금 고치려면 파일을 편집하고, 내용을 크게 재검토하려면 전체 맥락을 파악한 AI에게 수정을 맡기세요.

“시작한 뒤 제안(또는 사양)을 어떻게 업데이트하나요?”

그대로 업데이트하면 됩니다. 같은 변경 사항을 다듬는 것입니다.

확장 명령을 사용한다면 산출물을 편집한 다음 /opsx:continue를 실행해 새 상태에서 이어가거나, 업데이트된 계획에 따라 구현을 계속하려면 /opsx:apply를 실행하는 것이 자연스럽습니다. 기본 core 명령을 사용한다면 산출물을 편집하고 /opsx:apply를 실행하세요. 현재 파일을 읽기 때문에 산출물에 기록된 최신 내용을 기준으로 구현합니다.

기억할 점은 산출물이 서명된 계약이 아니라 현재 진행 중인 계획이라는 것입니다. AI는 항상 최신 내용을 기준으로 작업하므로 산출물을 편집해 진행 방향을 조정할 수 있습니다.

You: I want to change the approach in this change.

You: [edit design.md, or tell the AI:]
     Update design.md to use a background job instead of a synchronous call.

AI:  Updated design.md. The task list still fits; want me to continue applying?

You: /opsx:apply

이것으로 자주 묻는 질문에 답할 수 있습니다. 별도의 “제안 업데이트” 명령은 필요하지 않으므로 존재하지 않습니다. 파일이 기준 정보이며, 직접 또는 AI를 통해 파일을 편집하는 것이 업데이트입니다.

“구현한 뒤 어떻게 검토 단계로 돌아가나요?”

돌아갈 필요가 없습니다. 애초에 검토를 떠난 적이 없기 때문입니다. 워크플로는 유연합니다. 검토, 편집, 구현은 한 번 지나가면 되돌아갈 수 없는 순차 단계가 아닙니다.

구체적으로 /opsx:apply로 어느 정도 작업한 뒤에는 다음과 같이 할 수 있습니다.

• 계획을 다시 살펴보고 싶나요? 산출물을 열어 읽거나 터미널에서 openspec show <change>를 실행해 한데 모아 확인하세요.
• 수정할 부분을 찾았나요? 산출물을 직접 편집하거나 AI에게 요청한 다음 계속 진행하세요.
• 코드가 계획과 일치하는지 체계적으로 확인하고 싶나요? 확장 명령인 /opsx:verify를 실행하세요. 아무것도 차단하지 않으면서 완전성, 정확성, 일관성을 보고합니다. 워크플로: 검증을 참조하세요.

구현 이후를 포함해 언제든 검토할 수 있으므로 돌아가야 할 “검토 단계”는 따로 없습니다.

“코드를 직접 편집했어요. OpenSpec과 어떻게 조정하나요?”

자주 발생하는 일이며 문제없습니다. 편집기에서 코드를 수정한 결과 코드와 산출물의 내용이 달라졌다면, 어느 쪽이 맞는지 판단해 다시 일치시키면 됩니다.

• 코드가 맞고 사양이 오래됐습니다. 실제로 배포한 동작을 설명하도록 델타 사양과(필요하면) 작업 목록을 업데이트하세요. 보관하면 사양이 기준 정보에 병합되므로, 보관 전에 사양이 실제 동작과 일치해야 합니다.
• 사양이 맞고 코드가 달라졌습니다. 코드가 사양과 일치할 때까지 구현하거나 수정하세요.

불일치를 빠르게 찾으려면 /opsx:verify를 사용하세요. 산출물과 코드를 읽고 둘이 다른 부분을 알려 줍니다. 결과를 조정 작업 목록으로 활용하고, 내용이 일치한 뒤 보관하세요.

원칙은 다음과 같습니다. 보관 시점에 사양이 공식 기록이 됩니다. 따라서 보관하기 전에 사양이 코드의 실제 동작을 정확히 반영하도록 하세요. 직접 편집해도 좋지만, 사양과 코드가 조용히 어긋난 채 남지 않도록 주의하세요.

마음에 들지 않는 제안 다듬기

생성된 제안이 기대에 맞지 않는다면 다음 세 가지 방법을 사용할 수 있습니다.

• 기존 내용을 반복 개선합니다. “범위가 너무 넓으니 관리자 기능은 빼 줘”처럼 문제를 설명하고 AI가 수정하도록 하세요. 가장 저렴하며 대개 적절한 방법입니다.
• 먼저 탐색한 뒤 새로 제안합니다. 아이디어 자체가 불분명하다면 /opsx:explore로 돌아가 충분히 생각한 다음 더 명확한 제안을 작성하세요. 먼저 탐색하기를 참조하세요.
• 새로 시작합니다. 의도가 근본적으로 바뀌었다면 기존 내용을 고치는 것보다 새 변경 사항을 시작하는 편이 명확할 수 있습니다.

마지막 방법을 선택할지 판단하는 기준은 다음 섹션에서 설명합니다.

기존 변경 사항 업데이트와 새 변경 사항 시작의 기준

간단히 말하면 같은 작업을 다듬는 경우에는 업데이트하고, 의도가 근본적으로 바뀌었거나 범위가 별개의 작업으로 크게 확장된 경우에는 새로 시작하세요.

• 목표는 같고 접근 방법만 개선됐나요? 업데이트하세요.
• 범위가 좁아졌나요(지금 MVP를 배포하고 나머지는 나중에 진행)? 업데이트한 뒤 보관하고, 2단계 작업은 새 변경 사항으로 만드세요.
• 문제 자체가 바뀌었나요(“다크 모드 추가”가 “전체 테마 시스템 구축”으로 바뀜)? 새 변경 사항을 시작하세요.

전체 흐름도와 예제는 워크플로: 업데이트와 새로 시작하기에, 더 자세한 설명은 OPSX: 업데이트와 새로 시작하기에 있습니다.

작업 목록 참고 사항

tasks.md는 고정된 계획이 아니라 계속 갱신되는 체크리스트입니다. 구현 도중 발견한 작업을 추가하거나 불필요해진 항목을 삭제하고 순서를 바꿀 수 있습니다. AI는 /opsx:apply를 진행하며 완료한 항목을 체크하고, 나중에 다시 시작하면 첫 번째 미완료 작업부터 이어갑니다. 진행 중 목록을 편집하는 것은 자연스러운 일입니다.

다음 단계

• 워크플로 — 패턴과 업데이트/새로 시작 결정 가이드
• 변경 사항 검토 — 구현 전 계획을 2분 동안 점검하는 방법
• 먼저 탐색하기 — 아이디어를 다시 생각해 봐야 할 때 돌아갈 곳
• 명령 — /opsx:continue, /opsx:apply, /opsx:verify 상세 설명
• 개념: 산출물 — 각 산출물의 목적