Codex, OpenSpec 및 Superpowers 사용을 위한 팀 SOP

목적
이 SOP는 요구사항 발견 (requirements discovery), 제품 기획 (product planning), 구현 (implementation), 테스트 (testing), 검증 (validation), 운영 분석 (operations analysis), 문제 해결 (troubleshooting) 및 지식 캡처 (knowledge capture)를 위해 팀이 Codex, OpenSpec 및 Superpowers를 어떻게 사용해야 하는지를 정의합니다. 이 SOP는 소프트웨어 엔지니어만을 위한 것이 아닙니다. 제품 관리자 (product managers), QA 엔지니어 (QA engineers), 디자이너 (designers), 운영 팀 (operations teams), 고객 성공 팀 (customer success teams), 구현 및 인도 팀 (implementation and delivery teams), 데이터 분석가 (data analysts), 그리고 프로젝트 컨텍스트 (project context)를 보존해야 하는 모든 비즈니스 팀에도 적용됩니다.

핵심 목표:

새로운 팀원이 Codex를 사용하는 장벽을 낮춥니다.
프로젝트 컨텍스트가 채팅 기록에만 머무는 것을 방지합니다.
Codex 스레드가 컨텍스트를 잃었을 때 인간이 모든 것을 다시 말해야 하는 상황을 피합니다.
OpenSpec을 사용하여 요구사항, 결정 사항, 작업 진행 상황, 검증 결과 및 비즈니스 결론을 구조화된 방식으로 기록합니다.
Superpowers를 사용하여 빈번하고 복잡한 작업을 패키징하고 팀 협업 효율성을 향상시킵니다.
팀 지식을 재사용 가능하고, 전수 가능하며, 지속적으로 개선될 수 있도록 만듭니다.

빠른 시작: 신규 팀원을 위한 5분 버전
프로젝트에서 Codex를 처음 사용하는 경우, 다음의 최소 흐름으로 시작하십시오:

Codex에게 관련 컨텍스트가 OpenSpec에 이미 존재하는지 확인하도록 요청합니다.
이 작업에 새로운 OpenSpec 변경 사항이 필요한지, 아니면 기존 것을 업데이트해야 하는지 결정합니다.
작은 작업의 경우 바로 진행합니다. 더 큰 작업의 경우, 제안서 (proposal), 설계 (design) 및 작업 (tasks)을 먼저 작성합니다.
실행 중에는 작업에 따라 진행합니다. 주요 결정 사항을 채팅에만 남겨두지 마십시오.
완료 후에는 필요한 검증 (validation)을 수행하고 검증 방법과 결과를 기록합니다.
실제 출력물, 주요 결정 사항 및 남은 이슈를 OpenSpec에 다시 작성합니다.
변경 사항이 완료되면 스펙 (specs)을 업데이트해야 하는지 확인한 후, 적절한 경우 이를 아카이브 (archive)합니다.

최소 진입 프롬프트 (Minimal entry prompt):
이 프로젝트에서 이 작업을 수행하는 것이 처음입니다. 먼저 OpenSpec에 관련 컨텍스트가 이미 포함되어 있는지 확인한 다음, 다음을 알려주세요:

OpenSpec 변경 사항을 생성하거나 업데이트해야 하는지 여부
사용하기에 적합한 Superpower가 있는지 여부 4. 실행 가능한 최소한의 경로(Minimum Viable Path)가 무엇인지 여부 5. 어떤 조치에 나의 확인이 필요한지 여부

OpenSpec 사용 여부 결정하기
OpenSpec은 재사용 가능한 장기적 컨텍스트 (Context)를 보존하기 위해 존재합니다. 모든 작은 작업을 프로세스로 만들기 위한 것이 아닙니다. 작업을 시작하기 전에 가벼운 판단을 내리세요: 미래의 팀원, 미래의 나, 또는 새로운 Codex 스레드 (Thread)가 나중에 이 컨텍스트를 복구해야 할 필요가 있는가? 만약 대답이 "예"라면, OpenSpec 사용을 고려하십시오.

OpenSpec 사용에 적합한 사례:

요구사항 (Requirements), 솔루션 설계 (Solution Design), 수락 기준 (Acceptance Criteria) 또는 비즈니스 규칙 (Business Rules)을 장기적으로 보존해야 하는 경우.
작업이 여러 사람, 부서, 기간 또는 Codex 스레드에 걸쳐 있는 경우.
미래의 담당자가 왜 그런 결정이 내려졌는지 이해해야 하는 경우.
작업이 제품 동작, 기술 설계, 테스트 범위, 데이터 정의, 고객 인도 또는 운영 워크플로우 (Operational Workflows)에 영향을 미치는 경우.
주요 결정, 리스크, 검증 결과 또는 회고 결론을 기록해야 하는 경우.
완료된 작업이 향후 요구사항, 테스트, 릴리스, 인도 또는 비즈니스 판단에 영향을 미칠 수 있는 경우.

전체 OpenSpec 흐름이 필요하지 않을 수 있는 사례:

일회성 단순 질의응답.
작은 문구, 서식, 레이아웃 또는 로컬 설명 변경.
명확하게 리스크가 낮은 기계적인 편집.
보존할 가치가 있는 결정을 생성하지 않는 일시적인 탐색.
Codex에게 짧은 콘텐츠의 설명, 번역, 다듬기 또는 요약을 요청하는 경우.

권장 등급:
작업 유형 | 권장 처리 방식
단순 Q&A, 설명, 번역, 다듬기 | Codex에게 직접 완료하도록 요청하십시오.

OpenSpec 불필요 | 장기적인 영향이 없는 작고 위험도가 낮은 작업 | 가벼운 판단만으로 충분함

OpenSpec 필요 | 요구사항, 솔루션 설계, 수락 기준 (Acceptance Criteria), 테스트, 전달 또는 비즈니스 영향이 있는 작업 | OpenSpec 변경 사항을 생성하거나 업데이트하십시오.

OpenSpec 필수 | 팀 간, 스레드 간, 장기 실행 또는 고위험 작업 | 작업을 기록하고 추진하기 위해 반드시 OpenSpec을 사용해야 합니다.

한 줄 원칙: OpenSpec은 모든 대화와 작은 행동을 기록하기 위한 것이 아니라, 장기적으로 가치 있는 컨텍스트 (Context)를 보존하기 위한 것입니다.

기본 원칙 (Basic Principles)
모든 프로젝트는 장기적인 컨텍스트를 유지하기 위해 OpenSpec을 사용할 수 있어야 하지만, 모든 작은 작업이 전체 OpenSpec 프로세스를 따를 필요는 없습니다. OpenSpec은 프로젝트 반복 (Iteration) 컨텍스트의 구조화된 기록입니다. 이는 다음 사항을 보존하는 데 사용됩니다:

프로젝트 컨벤션 (Conventions)
요구사항 배경 (Requirement background)
솔루션 설계 (Solution design)
작업 세분화 (Task breakdowns)
실행 진행 상황 (Execution progress)
주요 결정 사항 (Key decisions)
검증 결과 (Validation results)
비즈니스 결론 (Business conclusions)
후속 항목 (Follow-up items)

컨텍스트의 소스로서 Codex 대화 기록에만 의존하지 마십시오. 만약 다음과 같은 상황이 발생한다면:

Codex가 모델의 컨텍스트 윈도우 (Context window) 용량을 초과한 경우: 새로운 스레드를 시작하거나, 다시 시도하기 전에 이전 기록을 삭제하십시오.

팀원들은 전체 배경을 구두로 다시 설명하는 대신 OpenSpec을 통해 작업 컨텍스트를 복구할 수 있어야 합니다.

컨텍스트 예산 원칙 (Context Budget Principles)
Codex, OpenSpec, 기술 (Skills), Superpowers, 로컬 도구, 규칙 설명, 프로젝트 문서 및 채팅 기록은 모두 모델의 컨텍스트 윈도우를 소비합니다. LLM의 컨텍스트 윈도우는 제한적입니다. 컨텍스트가 복잡할수록 모델이 한 번에 처리해야 할 정보가 많아지며, 실제 작업에 할당될 주의력 (Attention)은 줄어듭니다. 따라서 팀은 다음 원칙을 따라야 합니다:

도구가 많다고 항상 더 좋은 것은 아닙니다.
규칙이 많다고 항상 더 좋은 것은 아닙니다.
복잡한 워크플로우는 필요할 때만 패키징해야 하며, 기본적으로 Superpowers로 전환해서는 안 됩니다.

다음 사항에 특별히 주의하십시오:

한꺼번에 방대한 양의 무관한 배경 정보를 Codex에 밀어 넣지 마십시오.
단순한 작업을 위해 복잡한 Superpowers를 활성화하지 마십시오.

Codex가 동시에 너무 많은 임시 규칙을 따르게 하지 마십시오. 단순히 "적절해" 보이기 위해 Codex가 관련 없는 문서를 읽게 하지 마십시오. OpenSpec을 계속 쌓이는 로그로 만들지 마십시오. 가치가 낮은 정보로 장기적인 컨텍스트 (Context)를 오염시키는 것을 피하십시오. 모든 작은 동작을 Superpower로 만들지 마십시오. 하나의 Superpower가 거대한 범용 워크플로우 (Workflow)가 되도록 두지 마십시오. 권장되는 판단 기준: 규칙, 도구, 기술 또는 Superpower가 현재 작업에 명확하게 도움이 되지 않는다면, 이를 활성화하지 마십시오. 더 나은 실천 방법: 진정으로 필요한 OpenSpec 컨텍스트 (Context)만 읽으십시오. 현재 작업과 직접적으로 관련된 기술이나 Superpower만 활성화하십시오. 모든 요구사항을 한꺼번에 로드하는 대신, 복잡한 작업은 단계별로 나누십시오. 의미 있는 단계가 끝날 때마다 채팅 기록에 의존하는 대신, 주요 결정 사항을 OpenSpec에 기록하십시오. 프롬프트 (Prompt)는 짧고, 명확하며, 목표 지향적으로 유지하십시오. 한 줄 원칙: 컨텍스트 (Context)는 예산이지, 쓰레기통이 아닙니다.

세 가지 도구의 역할

Codex
Codex는 작업 이해, 컨텍스트 (Context) 읽기, 정보 정리, 분석 지원, 자동화 가능한 작업 실행, 검증 실행 및 결과 요약을 담당합니다. Codex는 실행자이자 협업자입니다.

OpenSpec
OpenSpec은 장기적인 컨텍스트 (Context)를 보존하는 역할을 합니다. 이는 프로젝트의 구조화된 메모리 (Memory)입니다. 무언가가 왜 수행되었는지, 어떻게 수행되었는지, 그리고 얼마나 진행되었는지를 기록합니다.

Superpowers
Superpowers는 빈번하고 복잡한 작업들을 패키지화합니다. 오류가 발생하기 쉽고, 여러 단계가 필요하며, 숙련된 경험이 요구되는 워크플로우 (Workflow)를 팀원들이 자연어로 호출할 수 있는 재사용 가능한 기능으로 변환합니다.

권장되는 사고 모델: OpenSpec은 컨텍스트 (Context)를 보존합니다. Superpowers는 복잡한 워크플로우 (Workflow)를 패키지화합니다. Codex는 작업을 이해하고, 도구를 선택하며, 프로세스를 실행하고, 기록을 업데이트합니다.

Codex 사용을 위한 참고 사항 및 팁
Codex는 정보 정리, 솔루션 탐색, 파일 편집, 검증 및 단계별 요약에 특히 유용합니다.

하지만 Codex의 효과는 작업 설명(task description)의 품질, 컨텍스트(context)의 품질, 그리고 검증 방식에 크게 좌우됩니다.

작업을 명확하게 만들기
좋은 Codex 작업에는 다음 사항이 포함되어야 합니다:

목표(Goal): 달성하고자 하는 것.
배경(Background): 이것이 왜 중요한지.
범위(Scope): 포함되는 것과 제외되는 것.
입력(Input): 관련 파일, 문서, 링크, 데이터 또는 컨텍스트.
출력(Output): 코드, 문서, 표, 요약, 제안서 또는 체크리스트 중 기대하는 결과물.
검증(Validation): 작업이 완료되었음을 어떻게 알 수 있는지.

권장 프롬프트(Recommended prompt):
나의 목표는 다음과 같습니다: [goal]
배경은 다음과 같습니다: [background]
범위에는 다음이 포함됩니다: [scope]
다음은 명시적으로 제외됩니다: [out of scope]
먼저 필요한 컨텍스트를 확인한 다음, 실행 계획을 제공해 주세요. 파일을 수정해야 하는 경우, 무엇을 변경할지 먼저 설명해 주세요. 완료 후에는 검증 방법과 결과를 설명해 주세요.

실행하기 전에 Codex에게 판단을 요청하기
복잡한 작업의 경우, Codex에게 즉시 "그냥 끝내줘"라고 요청하지 마세요. 더 나은 패턴은 Codex가 먼저 판단하게 하는 것입니다:

OpenSpec을 읽어야 하는지 여부.
변경 사항을 생성하거나 업데이트해야 하는지 여부.
Superpower가 필요한지 여부.
고위험 작업이 포함되어 있는지 여부.
사용자 확인이 필요한지 여부.

권장 프롬프트(Recommended prompt):
이 작업의 복잡성과 위험도를 먼저 평가해 주세요: 1. OpenSpec이 필요한지 여부 2. Superpower가 필요한지 여부 3. 어떤 컨텍스트를 읽어야 하는지 4. 파일이 수정되거나 외부 시스템에 영향을 미치는지 여부 5. 어떤 단계에서 나의 확인이 필요한지
해당 평가가 완료된 후에만 진행하세요.

모든 것을 한꺼번에 로드하는 대신 컨텍스트를 제어하기
Codex에게 모든 문서, 모든 규칙, 모든 과거 채팅 내역을 한꺼번에 주지 마세요.
더 나은 관행:

목표와 가장 중요한 배경을 먼저 제공하세요.
Codex가 필요한 컨텍스트를 스스로 검색하거나 식별하도록 하세요.
자료를 단계별로 추가하세요.
장기적으로 중요한 정보는 OpenSpec에 작성하세요.
임시 대화의 세부 사항은 채팅 내역에 묻혀 있게 두지 말고 적시에 요약하세요.

명시적으로 검증(Validation)을 요구하세요. 단순히 "완료되었습니다(done)."라는 답변만 수용하지 마세요. 작업이 끝날 때, Codex에게 다음 사항을 설명하도록 요청하세요:

무엇을 수행했는가.
무엇을 변경했는가.
결과를 어떻게 검증했는가.
검증 결과는 무엇인가.
검증되지 않은 상태로 남아 있는 것은 무엇인가.
남아 있는 리스크나 후속 조치는 무엇인가.

역할에 따라 검증 방식은 다릅니다:

역할 / 시나리오	일반적인 검증 방법
제품 (Product)	수락 기준 (Acceptance criteria) 확인, 사용자 흐름 (User flow) 검토, 범위 (Scope) 확인
엔지니어링 (Engineering)	테스트, 린트 (Lint), 빌드, 페이지 또는 API 검증
QA	테스트 커버리지 (Test coverage), 재현 단계 (Reproduction steps), 회귀 테스트 (Regression) 결과, 결함 상태
운영 / 비즈니스 (Operations / business)	지표 정의 (Metric definition) 확인, 실행 체크리스트, 회고 결론
데이터 분석 (Data analysis)	데이터 소스 확인, 지표 일관성, 이상치 (Outlier) 확인
고객 성공 / 구현 (Customer success / implementation)	고객 설정 확인, 인도 체크리스트 (Delivery checklist), 리스크 확인

고위험 작업 시 중단 및 확인 (Stop and Confirm)
다음 작업들은 Codex가 계획을 설명하고 인간의 확인을 기다려야 합니다:

파일 삭제, 덮어쓰기 또는 일괄 수정 (Batch-modifying).
데이터베이스 마이그레이션 (Database migrations), 운영 데이터 변경 또는 운영 설정 업데이트.
릴리스, 배포, 롤백 또는 실제 사용자에게 영향을 미치는 작업.
고객 설정, 인도 범위 또는 외부 약속에 영향을 미치는 작업.
공식적인 결론, 보고서 또는 외부 커뮤니케이션 전송.

단계별 요약 (Stage Summaries) 사용하기
작업이 길거나, 정보량이 많거나, 새로운 스레드로 이동하기 직전이라면 Codex에게 요약을 요청하세요:
"현재 컨텍스트를 기반으로 단계별 요약을 작성해 주세요:

현재 목표
완료된 작업
남은 작업
주요 결정 사항
검증 결과
현재 리스크
권장되는 다음 단계"

장기적으로 보존해야 할 정보는 OpenSpec에 작성하세요.
한 줄 원칙: Codex에게 맥락이나 검증 없는 마지막 도약(Final leaps)을 줄이고, 더 검증 가능한 중간 단계(Intermediate steps)를 수행하도록 요청하세요.

적용 가능한 역할 및 전형적인 시나리오
서로 다른 역할이 동일한 OpenSpec 방식을 사용할 수 있습니다. 차이점은 각 역할이 기록하는 데 집중하는 대상입니다.

역할	전형적인 시나리오	OpenSpec에 기록할 내용
Product manager (제품 관리자)	요구사항 분석, 사용자 스토리 (user stories), PRD 세분화, 범위 확정, 출시 계획	배경, 목표, 비목표 (non-goals), 수락 기준 (acceptance criteria), 주요 결정 사항, 범위 변경 사항
Software engineer (소프트웨어 엔지니어)	기술 설계, 기능 구현, 리팩토링 (refactoring), 버그 수정, API 변경	기술 설계, 영향 범위, 구현 진행 상황, 검증 결과, 리스크
QA engineer (QA 엔지니어)	테스트 계획, 테스트 케이스 설계, 결함 재현, 회귀 검증 (regression validation), 수락 보고서	테스트 범위, 테스트 데이터, 재현 단계, 실제 결과, 잔여 리스크
Designer (디자이너)	UX 제안, 인터랙션 변경, 디자인 리뷰, 시각적 표준 문서화	디자인 목표, 사용자 여정 (user journeys), 트레이드오프 (trade-offs), 수락 기준, 영향을 받는 페이지
Operations / business team (운영 / 비즈니스 팀)	캠페인 계획, 프로세스 최적화, 고객 이슈 후속 조치, 비즈니스 규칙 변경	비즈니스 배경, 목표 지표, 실행 계획, 검증 정의, 회고 결론
Data analyst (데이터 분석가)	지표 정의, 데이터 정의, 분석 결론, 보고서 반복	지표 정의, 데이터 소스, 분석 가정, 결론, 후속 조치
Implementation / customer success (구현 / 고객 성공 팀)	고객 인도, 문제 해결, 컨

Codex, OpenSpec 및 Superpowers 사용을 위한 팀 SOP

요약

핵심 포인트

댓글