먼저 탐색하기

/opsx:explore는 여러분의 사고 파트너입니다. 문제가 있지만 아직 계획이 없을 때 언제든 사용하세요. 이 명령은 코드베이스를 조사하고, 여러분과 함께 옵션을 비교하며, 실제로 원하는 것이 무엇인지 명확히 합니다. 모든 산출물이나 코드 한 줄이 작성되기 전에요. 상황이 명확해지면 /opsx:propose로 인계합니다.

이 문서에서 한 가지 습관을 가져가야 한다면, 이것을 가져가세요: 확신이 없을 때는 제안하기 전에 탐색하세요.

이것이 중요한 이유는 이렇습니다. AI 코딩 어시스턴트는 열정적입니다. 모호하게 질문하면 무언가를 자신 있게 만들어 주지만, 여러분이 실제로 필요로 한 것이 아닐 수 있습니다. 탐색이 바로 그 해결책입니다. 무위험 대화에서 여러분과 AI가 함께 올바른 방향을 찾아내므로, 제안할 때쯤에는 올바른 것을 제안하게 됩니다.

탐색할 때

사람들이 예상하는 것보다 훨씬 더 자주 탐색이 올바른 첫 단계입니다. 다음 중 하나라도 해당되면 사용하세요:

• 문제는 알지만 해결책은 모르는 경우. ("페이지가 느려요." "인증이 엉망이에요." "중복 주문이 계속 생겨요.")
• 접근 방식 사이에서 선택해야 하고, 실제 코드에 기반한 트레이드오프를 알고 싶은 경우.
• 코드베이스에 처음 온 경우이고, 변경하기 전에 어떻게 작동하는지 이해해야 하는 경우.
• 요구사항이 불분명하고, 확신하기 전에 명확히 하고 싶은 경우.
• 작업이 보이는 것보다 더 크거나 작을 수 있다고 의심하고, 정직하게 범위를 파악하고 싶은 경우.

정확히 무엇을 어떻게 해야 하는지 이미 알고 있을 때만 탐색을 건너뛰세요. 그 경우 바로 /opsx:propose로 가세요.

탐색이 하는 일 (하지 않는 일 포함)

탐색은 대화이지 생성기가 아닙니다.

하는 일:

• 코드베이스를 읽고 검색하여 실제 질문에 답합니다.
• 옵션을 비교하고 각각의 트레이드오프를 명시합니다.
• 다이어그램을 그려 설계를 가독성 있게 만듭니다.
• 모호한 아이디어를 구체적이고 구현 가능한 범위로 좁히는 데 도움을 줍니다.
• 준비가 되면 /opsx:propose로 전환합니다.

하지 않는 일:

• 변경 폴더를 생성하지 않습니다.
• 산출물을 작성하지 않습니다 (제안서, 스펙, 설계, 작업 없음).
• 코드를 작성하거나 수정하지 않습니다.

이것이 핵심입니다. 탐색은 비용이 들지 않고, 아무것도 구속하지 않습니다. 세 가지 실패한 경로를 탐색하고 각각에서 무언가를 배운 후, 살아남은 경로만 제안할 수 있습니다.

이미 설치되어 있습니다

좋은 소식: /opsx:explore는 기본 core 프로필에 포함되어 있으며, propose, apply, update, sync, archive와 함께 제공됩니다. 활성화할 필요가 없습니다. 프로젝트에 OpenSpec가 설정되어 있다면, AI 채팅에서 바로 탐색을 사용할 수 있습니다. (모든 /opsx:* 명령과 마찬가지로, 터미널이 아닌 어시스턴트 채팅에서 입력합니다. 명령 작동 방식 참조.)

전체 예시

모호한 우려가 명확하고 구현 가능한 변경으로 어떻게 변하는지 지켜보세요.

You: /opsx:explore

AI:  What would you like to explore?

You: Our checkout sometimes creates duplicate orders. I don't know why
     and I don't know how to fix it safely.

AI:  Let me dig into the checkout path...
     [reads the order service, the payment webhook handler, and the
      client submit logic]

     Here's what I found. There are two ways a duplicate can happen:

     1. The client can submit twice (double-click, retry on slow network).
        Nothing debounces it.
     2. The payment webhook can fire more than once, and the handler
        creates an order each time. There's no idempotency key.

     Cause #2 is the dangerous one: it can charge and fulfill twice.

     Three ways to fix it, roughly in order of robustness:
     - Idempotency key on the order-creation endpoint (handles both causes)
     - Dedup on the webhook by payment-intent id (handles #2 only)
     - Client-side debounce (handles #1 only, papers over the real bug)

     Given your code already stores the payment-intent id, the
     idempotency-key approach is a small change with the biggest payoff.
     Want me to scope that?

You: Yes, let's do the idempotency key.

You: /opsx:propose add-order-idempotency-key

AI:  Created openspec/changes/add-order-idempotency-key/, with a proposal
     and delta spec grounded in what we just found. Ready for implementation.

무엇이 일어났는지 주목하세요. 시작점은 "무언가 잘못되었고 건드리기 두렵다"였습니다. 20초의 탐색이 이를 명명된 근본 원인으로, 세 가지 순위 매겨진 옵션으로, 기존 코드에 기반한 권장 사항으로, 그리고 정확한 변경으로 전환시켰습니다. 뒤따르는 제안서가 날카로운 이유는 사고가 먼저 이루어졌기 때문입니다.

propose로 인계하기

탐색은 무엇에도 아카이브되지 않습니다. 준비가 되면 단순히 변경을 시작하면 되고, AI가 대화의 컨텍스트를 산출물로 가져갑니다.

explore  ──►  propose  ──►  apply  ──►  archive
 (think)     (agree)       (build)     (record)

일반적인 언어로 말할 수 있습니다 ("이걸 변경으로 만들어보자") 또는 /opsx:propose <name>을 직접 실행할 수 있습니다. 어느 쪽이든, 방금 한 탐색은 폐기할 채팅이 아니라 제안서의 기반이 됩니다.

확장된 명령 세트를 사용한다면, 탐색은 단계별 산출물 생성을 위해 /opsx:new로 인계할 수도 있습니다. 워크플로 참조.

좋은 탐색을 위한 팁

• 해결책이 아닌 문제를 가져오세요. "로그인이 느려요"라고 하면 AI가 조사할 여지가 생깁니다. "Redis 캐시를 추가하자"라고 하면 아직 검증하지 않은 답에 미리 구속됩니다.
• 트레이드오프를 직접 물어보세요. "각 옵션의 단점은 무엇인가요?"라고 하면 더 정직한 비교를 얻을 수 있습니다.
• 먼저 읽게 하세요. 가장 좋은 탐색은 AI가 추측하는 것이 아니라 실제로 코드를 보고 시작하는 것입니다. 도움이 된다면 관련 영역을 가리켜 주세요.
• 중도 포기해도 괜찮습니다. 탐색 결과 아이디어가 가치가 없다면, 그것이 승리입니다. 저렴하게 배운 것이니까요.
• 변경 중에도 다시 탐색하세요. /opsx:apply 중에 막혔나요? 한 발 물러서서 하위 문제를 탐색한 후 돌아올 수 있습니다.

정직한 트레이드오프

얻는 것: 탐색은 산출물이 존재하기 전에, 가장 저렴한 시점에 잘못된 방향을 잡아줍니다. 특히 익숙하지 않은 코드에서 강력하며, AI의 시스템 읽기와 요약 능력이 오후 내내 코드 탐험을 절약해 줍니다.

비용: 약간의 인내심. 탐색은 대화이므로 /opsx:propose를 바로 쏘고 기원하는 것보다 느립니다. 이미 충분히 이해하고 있는 작업에 대해서는 그 추가 단계가 순수한 오버헤드이며, 건너뛰어야 합니다.

기본 원칙: 작업이 더 불분명할수록 탐색의 효과가 더 큽니다. 작업이 더 명확할수록 바로 제안으로 건너뛸 수 있습니다.

다음 단계

• 명령: /opsx:explore: 정확한 참조
• 워크플로: 일상 루프의 일부로서의 탐색
• 예시 & 레시피: 전체 walkthrough에서의 탐색
• 시작하기: 첫 변경 가이드, 탐색 포함