OpenSpec 기각 제안: 의사결정 메모리 컨벤션

거부 상태가 없습니다. 다음은 임시 해결책입니다.

Page content

6개월 전 “영속성을 공유 라이브러리로 이동"을 제안하고 배포했던 에이전트는, 그 아이디어가 이미 검토되어 기각되었다는 것을 지속적으로 기록하는 것이 없다면 다음 분기에 같은 것을 다시 제안할 것이다 — 그리고 OpenSpec에는 현재 이를 위한 내장 상태가 없다.

/opsx:archive는 한 가지 결과, 즉 배포된 변경사항을 위해 설계되었다. 이것은 델타 스펙을 openspec/specs/에 동기화하고, 폴더를 openspec/changes/archive/YYYY-MM-DD-<name>/으로 이동시켜 무엇이 왜 변경되었는지에 대한 기록으로 남긴다. /opsx:reject나 /opsx:abandon과 같은 반대 명령은 없으며, 아카이브 형식에는 미래의 제안에 “이 정확히 동일한 아이디어가 검토되어 거절되었다"고 알리는 요소가 없다. 이 결여는 OpenSpec가 일반적으로 잘 맞는 코드베이스, 즉 소수의 기여자와 에이전트가 주기적으로 동일한 아키텍처 질문(이 두 서비스를 병합, 이 영속성 레이어 공유, 이 HTTP 경계를 직접 임포트로 교체)을 재탐색하는 브라운필드 시스템에서 가장 중요하다.

새로운 제안에 컨텍스트를 되돌리는 계층적 결정 아카이브

이것은 가상의 결여가 아니다. OpenSpec의 유지보수자들과 직접 기능 요청으로 제기되었고, 여러분이 자체 수정을 임провизировать(improvise)하기 전에 그 대화의 전개 방식은 가치 있는 지식을 제공한다: 프로젝트가 실제로 결론을 내린 것은 어떤 관례를 채택하는 것이 가치 있는지 결정하는 형태를 결정한다. 이 가이드는 /opsx:archive만 의존했을 때 일어나는 일, OpenSpec의 이슈 트래커에서 이미 발생한 실제 논의, 그리고 코어 지원이 없거나 필요하지 않게 기다리지 않고 오늘 바로 채택할 수 있는 경량 decision.md 패턴을 다룬다.

왜 아카이빙만으로는 기각된 결정을 기록하지 못하는가

구성하지 않기로 결정한 변경사항을 아카이브하는 것은 기술적으로 동작한다 – 폴더는 어떻게든 활성 목록에서 벗어나기 때문이다. 문제는 수십 개의 배포된 변경사항들과 함께 놓여 있을 때, 그 아카이브된 폴더가 전달하지 못하는 것이다:

  • 상태 필드 부재. 아카이브된 변경사항은 배포되었든 아니면 /opsx:propose에서 3번째 메시지에서 폐기되었든 외관이 동일하다. openspec/changes/archive/를 스캔하는 동료나 에이전트는 모든 제안 폴더를 열고 내부 산출물을 읽지 않는 한 차이를 알 수 없다.
  • 먼저 확인해야 하는 신호 부재. 기본 워크플로우에서 에이전트가 새 제안을 초안 만들기 전에 아카이브를 검색하도록 지시하는 것이 없다. /opsx:propose는 현재 요청과 코드베이스의 상태에서 초안을 작성한다, 그 뿐이다 – 그것이 지시되지 않으면 이전에 기각된 변경사항과 교차 참조하지 않는다.
  • 동기화하고 싶지 않은 델타 스펙. 기각된 변경사항에 이미 델타 스펙 초안이 있고 일반적인 방식으로 아카이브하면, /opsx:archive가 먼저 그 델타를 openspec/specs/에 동기화하도록 제안한다. 그 제안을 수락하는 것은 정규 스펙이 구현하지 않기로 결정한 동작을 기술하도록 가르치게 되며, 이는 모든 다른 제안이 계획하기 전에 읽는 “시스템이 현재 무엇을 하는가” 기록을 조용히 훼손한다.

이것은 버그가 아니다. /opsx:archive는 문서가 말하는 대로 정확히 하고 있다: 배포된 변경사항을 완료하는 것. 기각 케이스는 의도적으로 그 문서화된 범위를 벗어나 있으며, OpenSpec의 자체 팀 워크플로우 가이드는 그것이 권장하는 대부분의 것 – 브랜치 관례, PR 리뷰 순서, 언제 아카이브할지 – 이 도구 위에 겹쳐진 관례이지, OpenSpec가 여러분을 위해 강제하는 것이 아님을 명시한다. 기각을 처리하는 것은 여러분이 스스로 정의할 수 있는 또 다른 관례이며, CLI는 이미 이를 깔끔하게 수행하는 데 필요한 플래그를 제공한다: 배포하지 않는 변경사항을 아카이브할 때 --skip-specs를 전달하여, openspec archive investigate-shared-persistence --skip-specs가 openspec/specs/에 전혀 영향을 주지 않고 폴더를 정리한다.

OpenSpec의 유지보수자들이 ADR 지원에 대해 실제로 결정한 것

하우스 관례를 발명하기 전에, 이 정확한 질문이 공개적으로 어떻게 전개되었는지를 읽는 것이 가치가 있다, 왜냐하면 해결책은 “아니오"보다 더 구체적이고 – 더 흥미롭다. GitHub 이슈 #557은 2026년 1월에 일급 아키텍처 결정 기록(ADR) 지원 요청으로 열렸다: 단일 변경사항의 라이프사이클에 독립적으로 지속되는 지속 가능한 기록, 따라서 기각되거나 대체된 결정이 모든 미래 제안에 대해 가시적으로 남아있게 된다. 한 기여자가 이를 구현하는 풀 리퀘트를 열기까지 했다.

그 후, 리드 유지보수자 Tabish Bidiwale(@TabishB)와 여러 깊이 참여하는 커뮤니티 멤버들이 참여한 7개월에 걸친 진지한 왕복 논쟁이 이어졌다. 여기에는 불변 vs 가변 기록, ADR이 연구 단계에 속하는지 설계 단계에 속하는지, 하나의 결정이 수십 개의 후속 변경사항으로 파급될 때의 크로스-체인지 소유권, 그리고 ADR이 시스템의 “권위적” 설명으로서 스펙과 어떻게 관계되는지가 포함되어 있다. Tabish Bidiwale의 초기 프레이밍은 그 스레드가 최종적으로 정한 방향을 설정했다: OpenSpec는 기본적으로 경량으로 남아 있어야 하며, ADR과 같은 전문화 워크플로우는 코어에 박지 않고 스키마 시스템을 통해 구성 가능하게 만들어야 한다. 한 커뮤니티 멤버는 이후 논의가 도달한 곳을 요약했다:

ADR 워크플로우는 가치 있지만, OpenSpec에는 현재 일급/네이티브 ADR 지원이 없다… 여기서 논의된 방향은 기본 워크플로우를 경량으로 유지하고 전문화 워크플로우를 구성 가능하게 만드는 것이다.

유지보수자 Clay Good(@clay-good)은 2026년 8월에 그 근거로 이슈를 닫고, 대화이 해결되지 않은 버그로 열려 있지 않으면서도 계속 진화할 수 있도록 GitHub Discussion #1553으로 이동했다. 이는 기본적으로 Spec Kit 스타일의 의식을 피하는 것이 유일한 매혹인 도구로서 합리적인 판단이다. 이는 또한 수정이 한 층 위에, 두 곳 중 하나에 존재한다는 것을 의미한다:

  1. 커뮤니티 스키마. OpenSpec 기술 자문 Hari Krishnan(@harikrishnan83)이 구축하고 intent-driven.dev에 문서화된 spec-driven-with-adr 스키마는 OpenSpec의 기본 4산출물 파이프라인에 다섯 번째 산출물을 추가한다. 이는 기본 스키마가 변경사항이 아카이브되는 순간 design.md의 추론을 잃기 때문에 존재한다 – 스펙 델타만 앞으로 동기화되므로, 결정의 “왜"는 다른 것이 보존하지 않으면 변경사항과 함께 사라진다.
  2. 레포지토리 수준 관례. 작고 수동으로 만든 decision.md 파일과 이름짓기 규칙, 이는 채택하는 데 아무 비용도 들지 않고 커스텀 스키마 설치를 요구하지 않는다.

이 가이드의 나머지 부분은 옵션 2를 심층적으로 다룬다. 왜냐하면 대부분의 팀에 대해 더 낮은 마찰력의 시작점이기 때문이다 – 그리고 아래 커뮤니티 스키마에 대한 섹션이 보여주듯이, 기각 로그가 그보다 더 무거운 툴링으로 전환할 만큼 충분히 크면 나중에 해당 툴링으로 전환하는 것과 호환된다.

기각된 변경사항을 기록하기 위한 decision.md 관례

기각된 탐구를 배포된 것과 동일한 방식으로 구성하지만, 어떤 델타도 동기화하기 전에 멈추고, 결과를 명확히 서술하는 한 파일을 추가한다:

openspec/
  changes/
    archive/
      2026-09-16-rejected-shared-persistence-layer/
        proposal.md
        decision.md

decision.md는 적절한 아키텍처 결정 기록이 답하는 동일한 네 가지 질문 – 무엇이었는지, 왜였는지, 어떤 대안이 있었는지, 무엇이 답변을 바꿀지에 대해 답한다:

# Decision

Status: Rejected

## Decision

두 Go 서비스 간의 서비스 대 서비스 HTTP 경계를 직접 패키지 임포트로 대체하지 않는다.

## Reasons

- 독립적으로 배포되는 서비스 간의 컴파일 타임 결합을 증가시킨다.
- 영속성 레이어를 암묵적이고 문서화되지 않은 계약으로 만든다.
- 측정된 이익(레이턴시, 코드 중복)이 이 코드베이스의 결합 비용보다 작았다.

## Alternatives considered

- 공유 내부 Go 모듈 -- 동일한 결합 이유로 기각.
- HTTP 대신 gRPC -- 유보, 기각 아님; HTTP 오버헤드가 측정된 병목이 되면 재검토.

## Reconsider only if

- 두 서비스가 의도적으로 하나의 배포 단위로 병합되거나,
- 레이턴시 측정이 HTTP 홉이 입증된 병목임을 보여줄 때만.

## Related

- 아키텍처 규칙: 서비스는 공유 패키지가 아닌 HTTP로 통신한다.

이 전체 관례를 작동시키는 유일한 강력한 규칙: 기각된 변경사항에 대해 동기화 단계를 실행하지 않는다. 변경사항을 반대하기 전에 /opsx:propose가 이미 델타 스펙을 초안화했다면, CLI가 정확히 이 상황을 위해 제공하는 플래그를 사용한다:

openspec archive investigate-shared-persistence --skip-specs

--skip-specs는 openspec/specs/에 전혀 영향을 주지 않고 변경사항을 정리하도록 openspec archive에 지시하며, 이는 배포하지 않고 아카이브하는 모든 것에 대해 가장 안전한 기본값이다. 대신 일반적인 동기화 프롬프트를 수락하는 것은 기각된 아이디어의 델타 스펙을 정규 스펙에 병합하게 되며, 정규 openspec/specs/는 시스템이 현재 무엇을 하는지를 기술해야 할 뿐, 초안화되고 거절된 모든 아이디어를 기술해야 하는 것은 아니다. 만약 변경사항이 구조적 이유로(예: 순수한 조사 폴더) 영구적으로 스펙 변경을 생성하지 않는다면, OpenSpec도 플래그 없이 매번 깔끔하게 아카이브할 수 있도록 해당 변경사항의 .openspec.yaml에서 skip_specs: true를 선언하도록 지원한다.

인간과 에이전트가 아카이브를 스캔할 수 있도록 기각된 변경사항 이름짓기

decision.md 파일은 누군가 폴더를 열어야만 도움이 된다. 폴더 이름 앞에 결과를 접두사로 붙여, ls openspec/changes/archive/를 훑어보는 인간과 변경사항을 나열하는 에이전트 모두 단일 파일을 열지 않고도 상태를 알 수 있게 한다:

2026-09-16-rejected-shared-persistence-layer/
2026-09-20-abandoned-react-router-migration/
2026-10-01-superseded-old-auth-design/
2026-10-10-add-project-filtering/          # shipped, no prefix needed

이것은 이미 단독 결정 기록에 대해 권장되는 상태 어휘 – 제안됨, 수용됨, 대체됨, 비추천됨 – 을 별도 docs/decisions/ 폴더 대신 OpenSpec의 자체 아카이브에 적용한 것이다. 어휘를 작게 유지한다. 세 개나 네 개의 일관된 접두사가 모든 제안이 약간 다르게 표기하는 프리-텍스트 상태 라인보다 낫다.

에이전트가 다시 제안하기 전에 아카이브를 확인하도록 하는 방법

이름짓기와 decision.md 파일은 폴더를 훑어보는 인간에 대한 가시성을 해결한다. 새 제안을 초안 만들기 전에 에이전트가 아카이브를 검색하도록 하는 것에는 아무런 도움이 되지 않는다 – 이는 명시적인 지시여야 한다, 왜냐하면 /opsx:propose가 기본적으로 그것을 하지 않고, 아무리 깔끔한 파일 이름짓기라도 그 자체로 그것을 바꾸지 않기 때문이다.

그 지시를 넣을 두 곳, OpenSpec가 이미 프로젝트 특정 가이드라인이 주입되기를 기대하는 방식에 부합한다:

openspec/config.yaml에서, 모든 계획 요청에 주입되는 context: 필드 아래 (50KB 한도를 주의, OpenSpec 퀵스타트에서 다룸):

context: |
  Before proposing a change, search openspec/changes/archive for folders
  prefixed "rejected-" or "abandoned-" that describe a materially similar
  idea. If one exists, summarize its decision.md and state what has
  changed before proposing the idea again. Do not re-litigate a rejected
  decision without new evidence.

AGENTS.md나 프로젝트의 자체 에이전트 지침에서, 요청별 컨텍스트 blob이 아니라 상시 규칙으로서:

## Rejected OpenSpec changes

When a proposal is investigated and rejected:

1. Do not sync or apply its delta specs.
2. Add `decision.md` with Status, Decision, Reasons, Alternatives
   considered, and Reconsider only if.
3. Prefix the archived folder name: `rejected-<name>` or `abandoned-<name>`.
4. Before proposing a materially similar change, search
   `openspec/changes/archive/` and reference the prior decision.
5. Do not reopen a rejected decision unless its documented
   reconsideration conditions have actually changed.
flowchart TD A[New idea worth a change] --> B{Search openspec/changes/archive} B -->|Similar rejected decision found| C[Summarize prior decision.md] C --> D{Reconsideration conditions changed?} D -->|No| E[Do not re-propose. Reference the decision.] D -->|Yes| F["/opsx:propose with the changed context stated"] B -->|Nothing similar found| F

어떤 지시도 복종을 보장하지는 않는다 – 에이전트는 주입하는 다른 어떤 컨텍스트를 읽는 것을 건너뛸 수 있는 것과 같은 방식으로 검색 단계를 건너뛸 수 있다. 그러나 이는 “정보는 리포지토리의 어딘가에 존재한다"와 “에이전트가 매번 찾아보라고被告知된다” 사이의 차이이며, 실제로 반복된 조사를 줄이는 것은 오직 후자이다.

작동 예시: 제안 기각, 그리고 올바르게 재고하기

구체적인 사례로 조각들을 조합해 보자. 동료 한 명이 에이전트에게 서비스 간 HTTP 호출을 직접 Go 패키지 임포트로 교체하여 네트워크 레이턴시를 줄이는 것을 살펴보라고 요청한다고 가정하자.

  1. 탐색, 그리고 제안. /opsx:explore는 두 서비스를 읽고, /opsx:propose replace-http-with-direct-import는 제안서, 레이턴시 이득과 결합 비용을 저울질하는 설계 문서, 그리고 델타 스펙 초안을 작성한다.
  2. 조사와 기각. 설계 문서를 검토한 후, 팀은 결합 비용 – 독립적으로 배포되는 두 서비스가 이제 컴파일 타임 종속성을 공유하게 됨 – 가 아무도 실제로 문제로 측정하지 않은 레이턴시 이득보다 크다고 결정한다. 아무것도 구축되지 않는다.
  3. 동기화 없이 아카이빙. 폴더를 삭제하는 대신, openspec archive replace-http-with-direct-import --skip-specs를 실행하고, Status: Rejected, 위의 이유, 그리고 답변을 바꿀 조건을 지명하는 Reconsider only if 절(예: “레이턴시 측정이 HTTP 홉이 입증된 병목임을 보여줄 때”)을 가진 decision.md를 아카이브된 폴더에 추가한다. 폴더를 rejected- 접두사로 이름을 변경하여 openspec/changes/archive/2026-09-16-rejected-replace-http-with-direct-import/로 읽히도록 한다.
  4. 수개월 후, 누군가 다시 제기한다. 다른 기여자, 또는 새 세션에서 동일한 에이전트가 “체크아웃에서 재고로의 호출을 빠르게 하라"고 요청받고, 동일한 아이디어와 매우 유사해 보이는 제안 초안을 작성하기 시작한다. openspec/config.yaml이 에이전트에게 먼저 아카이브를 검색하도록 지시하므로, 기각된 폴더를 발견하고, decision.md를 읽고, 보고한다: “물질적으로 유사한 변경사항이 2026-09-16에 결합 이유로 제안되고 기각되었습니다. 재고 조건은 ‘레이턴시 측정이 HTTP 홉이 입증된 병목임을 보여줄 때’였습니다. 새로운 측정이 있습니까, 아니면 이것은 다른 문제입니까?”
  5. 팀이 새로운 증거를 제공한다. 프로파일링이 이제 HTTP 홉이 실제로 체크아웃 레이턴시를 지배하는 것을 보여준다면, 그것은 원래 decision.md가 요청한 정확히 변경된 상황이다. 에이전트는 /opsx:propose로 진행하고, 새 제안의 decision.md – 이 제안도 아카이브될 때, 수용되었든 기각되었든 –는 Related 아래에서 이전 것을 참조하므로, 아카이브는 우연히 동일한 아이디어를 기술하는 두 개의 연결되지 않은 폴더가 아니라 연속적인 결정 역사로 읽힌다.

그 다섯 번째 단계가 이 관례의 전체 목적이다. 없다면, 단계 4는 아예 일어나지 않는다 – 에이전트는 0에서 다시 조사할 뿐 – 또는 인간이 이전 대화를 기억했기 때문에 우연히 일어난다. decision.md 파일과 아카이브 검색 지시는 “누군가 기억할 수 있다"를 워크플로우가 실제로 확인하는 것으로 만든다.

OpenSpec의 아카이브 vs 전담 ADR 로그: 누가 무엇을 소유하는가

아카이브 내부에서 decision.md 파일을 유지보수하기 시작하면, 관례가 조용히 중복 문서로 변하지 않도록 어떤 산출물이 어떤 질문에 답하는지 명시하는 것이 가치가 있다:

Artifact Answers
openspec/specs/ 시스템은 현재 무엇을 하는가?
openspec/changes/<name>/ (active) 우리는 지금 무엇을 변경하려고 제안하는가?
openspec/changes/archive/<name>/ 과거에 무엇이 변경되었거나 (또는 기각되었거나) 왜 그랬는가?
docs/adr/ (standalone, tool-neutral) 우리는 어떤 지속 가능한 아키텍처 규칙을 학습했는가, 단일 변경사항과 독립적으로?

한 조사에 속할 만큼 충분히 좁은 결정 – “우리는 이 영속성 레이어를 공유하는 것을 보고 안 된다고 말했다” – 에 대해, 위의 아카이브 내부 decision.md 관례가 충분하다. 많은 미래 변경사항을 넘겨서 제약해야 할 결정 – “서비스는 HTTP로 통신하며, 절대 공유 패키지가 아니다” – 에 대해, docs/adr/의 단독 아키텍처 결정 기록으로 승격하고, 기각된 변경사항의 decision.md가 Related 아래에서 그것을 참조하도록 한다. 이 분리는 OpenSpec의 아카이브를 개별 조사에 초점을 맞추게 하고, ADR 로그는 단일 도구의 라이프사이클을 – OpenSpec를 완전히 떠나는 미래 이주를 포함하여 – 생존해야 할 소수의 규칙을 보유하게 한다.

언제 spec-driven-with-adr 스키마를 대신 채택해야 하는가

위의 수동 관례는 아무 비용도 들지 않고 15분의 설정 안에 맞춘다, 이는 올바른 기본값을 만든다. 그러나 이름짓기 접두사를 벗어나었다고 결정하기 전에, 더 구조화된 대안이 실제로 무엇을 하는지 이해하는 것이 가치가 있다.

spec-driven-with-adr는 OpenSpec의 파이프라인에서 design과 tasks 사이에 다섯 번째 산출물, adr를 삽입한다. ADR 콘텐츠를 변경사항 폴더에 직접 기록하는 대신, adr 단계는 짧은 변경사항 로컬 adr.md 리뷰 매니페스트를 생성하고, 변경사항이 진정한 지속 가능한 아키텍처 약속을 도입할 때, 레포지토리 루트에 번호 매겨진 기록 – /adr/0042-use-postgres-for-catalog.md, openspec/와 형제 관계, 그 안에 중첩되지 않음 – 를 생성한다. 스키마가 생성하는 모든 ADR은 수용되면 불변이다: 스키마의 자체 지침은 이것을 “철의 규칙"이라 부른다 – 수용된 기록의 상태, 본문, 날짜를 절대 편집하지 않는다. 이전 결정을 변경하려면, Supersedes: 필드가 이전 것을 지명하는 새 ADR을 작성하고, 미래 설계는 여전히 효력이 있는 결정이 무엇인지 알기 위해 그 대체 체인을 따른다. 이는 위의 decision.md 관례의 정확히 “재고하기만 하라” 아이디어의 더 엄격한 버전으로, 인간이 기록하기 위해 기억하는 것에 맡기지 않고 스키마에 의해 강제된다.

이 스키마가 무엇이고 무엇이 아닌지에 대해 정확히 하는 것이 가치가 있다. 이는 수용되어 아카이빙을 생존해야 하는 결정 – Postgres vs DynamoDB, JWT vs 세션 쿠키 – 을 위해 구축된 것이다, 아무것도 배포하지 않고 조사되고 기각된 제안이 아니다. 기각된 조사는 이 스키마 아래에서도 명확한 곳이 어디인지 없다; 당신은 이 가이드의 동일한 decision.md-and-naming 관례를 그 위에 겹쳐야 할 것이며, 다만 단독 docs/adr/ 폴더 대신 /adr/ 기록을 참조할 뿐이다.

다음 중 하나가 눈에 띄면 도달한다:

  • 기각된 결정의 수가 openspec/changes/archive/에서 접두사를 grep하는 것이 더 이상 빠르지 않을 정도로 크다.
  • 관례와 grep이 아니라 자동으로 모든 새 설계와 검증되고 교차 참조되는 지속 가능한 아키텍처 결정을 원한다.
  • 여러 기여자가 약간 다른 decision.md 형식을 계속 발명하고 있으며, 대신 하나의 불변, 번호 매겨진 형식을 강제하는 스키마를 원한다.

커스텀 스키마를 설치하는 것은 이름짓기 관례보다 큰 커밋이다 – 그것은 기각된 것만이 아니라 모든 미래 변경사항에 대해 /opsx:propose가 생성하는 것을 변경한다 – 따라서 경량 버전이 눈에 띄게 부담스러워질 때 단계의 상향으로 취급하라, 기본 첫 번째 움직임으로 değil.

결론

OpenSpec의 아카이브는 한 가지 결과 – 배포된 변경사항 – 을 중심으로 설계되었으며, 그 자체의 유지보수자들은 7개월에 걸친 공개 논의 후에 일급 기각 또는 ADR 지원이 곧 코어 워크플로우에 오지 않을 것임을 명시했다. 이는 OpenSpec가 이미 대부분의 팀 관례를 놓는 곳에 수정을 남긴다: 도구에서가 아니라 여러분의 레포지토리에. decision.md 파일, 아카이브에 대한 --skip-specs 플래그, rejected-/abandoned- 이름짓기 접두사, 그리고 제안하기 전에 아카이브를 검색하도록 에이전트에 지시하는 명시적인 지시는 대부분의 반복된 조사를 멈추는 데 충분하다. spec-driven-with-adr 스키마는 그 경량 관례가 추적하는 결정의 수 아래로 진정으로 부담스러워질 때만 도달하라 – 그리고 심지어 그럴 때라도, 구분을 명확히 유지하라: 그것은 여러분이 수용하고 아카이빙을 생존하기를 원하는 결정을 관리하는 것이지, 여러분이 거절한 것이 아니다.

유용한 링크

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.