EP11. 구조 기반 산출물 생성 활동 스킬
🏛️ 4대 전담 부대의 설계 원칙과 '침묵의 기본값' 깨부수기
지난 에피소드에서는 구조 없는 생성이 왜 위험한지, 그리고 ASR과 ADR이라는 개념이 어떻게 모호한 문서 구조를 단단하게 붙잡아주는지 그 철학을 이야기했습니다.
이번 편에서는 Cocrates Harness 안에서 이 파이프라인을 실질적으로 구동하는 네 가지 핵심 스킬(.opencode/skills/*/SKILL.md)의 내부 메커니즘을 상세히 파헤쳐 보겠습니다. 각 스킬은 고유의 원칙과 엄격한 금지 사항을 수호하며 최종 산출물의 품질을 보장합니다.
1. adr-writing: "왜 이런 결정을 내렸는가"
- 핵심 원칙:
1 ADR 파일 = 1 Concern (관심사)
Cocrates에서 ADR은 개발자들의 전유물인 'Architecture Decision Record'를 넘어, 'Any Decision Record'로 확장됩니다. 보고서의 서두를 어떻게 열지, 발표 자료의 슬라이드 전개를 어떻게 가져갈지 등 산출물에 영향을 미치는 모든 구조적 결정이 기록 대상입니다.
- 가짜 대안 제시 금지: "Option A가 좋으니, 나쁜 Option B를 대충 섞어 A를 돋보이게 하자"와 같은 편향된 선택지 구성은 엄격히 금지됩니다. 최소 2~3개의 대안은 모두 실질적이고 장단점이 팽팽한 선택지여야 합니다.
- 산문 스타일 금지: 장황한 설명은 인간의 의사결정을 방해합니다. 오직 이름과 2~4개의 간결한 불릿으로만 Trade-off를 요약해 한눈에 비교할 수 있도록 배치합니다.
- 승인 게이트: 모든 ADR은 최초 생성 시
proposed상태로adr/디렉토리에 박제되며, 사용자의 명시적인 구두 승인("좋아, B로 가자")을 얻은 뒤에야approved로 격상되어 아키텍처 감사 추적의 역할을 수행합니다.
2. spec-writing: "무엇을, 어떻게 만들기로 했는가"
- 핵심 원칙:
자체 완결성
ADR을 통해 결정이 내려졌다면, spec-writing 스킬이 바통을 이어받아 최종 설계도인 Spec(명세서)을 작성합니다. 이때 가장 중요한 규칙은 Spec 파일 하나만 읽어도 무엇을 어떻게 만들지 완벽하게 이해해야 한다는 점입니다.
- ADR 참조 금지: "상세 내용은
adr/01-database.md참고"와 같은 링크나 참조는 Spec 내부에서 절대 허용되지 않습니다. ADR이 결정을 내리기까지의 '과거 기록(왜)'이라면, Spec은 확정된 요구사항만 명시하는 '현재의 설계도(무엇을, 어떻게)'이기 때문입니다. 선택지의 비하인드 스토리는 모두 걷어내고, 오직 확정된 구현 명세만을 촘촘하게 기술합니다. - 검증 가능한(Verifiable) 항목: 장황한 줄글을 배제하고 하나의 항목(불릿)이 하나의 명확한 요구사항이나 제약을 담도록 서술합니다. 그래야 나중에 검증 부대가 합격/불합격을 명확히 발라낼 수 있습니다.
3. spec-driven-generation: "설계도대로 짓는다"
- 핵심 원칙:
Spec이 유일한 헌법이자 근거
실제 산출물의 텍스트나 코드를 출력하는 단계입니다. 이 스킬의 위대한 점은 "생성하기 전에 멈출 줄 안다"는 것에 있습니다.
🛑 ASR Readiness Gate
사용자가 설계도 없이 "당장 결과물부터 내놔라"라고 요청하면, 이 게이트가 작동하여 생성을 차단합니다. Cocrates는 무작정 펜을 잡는 대신, 모든 산출물에 공통으로 적용되는 8가지 보편 범주를 들이밀며 의사결정을 요구합니다.
ASR의 8가지 보편 범주: ① 목적과 독자, ② 산출물 형태, ③ 범위 경계, ④ 품질 기준, ⑤ 제약, ⑥ 구조와 구성, ⑦ 통합과 의존성, ⑧ 프로세스와 단계
최초의 프롬프트와 사후에 합의된 Spec이 충돌할 경우, Cocrates는 무조건 Spec을 우선시하여 반영합니다. 충동적인 첫 요청보다, 숙고를 거쳐 완성된 설계도가 진짜 유저의 의도라고 믿기 때문입니다.
4. spec-driven-verification: "설계도와 대조하라"
- 핵심 원칙:
이중 목적 검증 (Deviation & Undocumented ASR)
산출물이 생성되면 spec-driven-verification 스킬이 작동하여 현미경 검증을 시작합니다. 단순히 설계도대로 잘 만들었는지(Deviation 체크) 확인하는 것을 넘어, AI가 몰래 밀수입한 임의의 결정(Undocumented ASR)을 적발해 내는 것이 이 스킬의 백미입니다.
- Deviation: Spec에 명시된 규칙을 위반함 (예: "PostgreSQL 쓰라니까 MongoDB 씀") → [무조건 수정]
- Undocumented ASR: Spec에 없었지만 결과물에 구현됨 (예: "AI가 임의로 하위 섹션 배치") → [유저의 선택]
🧐 Undocumented ASR을 다루는 태도
AI가 임의로 추가한 구조나 내용이 무조건 틀린 것은 아닙니다. 때로는 AI의 즉흥적인 구조 제안이 더 훌륭할 때도 있죠. 문제는 사용자가 인지하지 못한 채 블랙박스로 넘어가는 상황 그 자체입니다. 검증 스킬은 이를 악착같이 찾아내 보고서(verification/)로 남긴 뒤 유저에게 삼지선다를 요구합니다: "그대로 둘까요(Confirm)? 설계도에 공식 추가할까요(Update)? 아니면 걷어낼까요(Fix)?"
📊 네 가지 전담 스킬 요약 매트릭스
| 스킬명 | 핵심 역할 | 산출물/출력 파일 경로 | 절대 금지 사항 (Constraints) |
|---|---|---|---|
adr-writing | 관심사별 대안 분석 및 결정 기록 | adr/{concern-slug}.md | 가짜 대안 섞기, 장황한 산문 서술 |
spec-writing | 승인된 결정을 하나의 설계도로 통합 | spec/{requirement-slug}.md | Spec 내부에서 ADR 파일 링크/참조하기 |
spec-driven-generation | 완결된 Spec을 유일한 근거로 최종 생성 | 산출물 본문 파일 | Spec 없이 무작정 생성하기 (Gate 통과 필수) |
spec-driven-verification | Spec 일치 여부 및 미문서화 구조 스캔 | verification/{requirement-slug}.md | 유저의 컨펌 없이 독단적으로 수정하기 |
🎬 다음 편 예고
지금까지 살펴본 ADR → Spec → Generation → Verification 파이프라인은 어떤 산출물에도 유연하게 적용할 수 있는 Cocrates Harness의 표준 아키텍처 빌드업 프로세스입니다.
그런데 만약, 우리가 만들어야 하는 산출물의 도메인이 극도로 구체적이고 반복적인 구조를 요구한다면 어떨까요? 매번 바닥부터 범용 8대 범주를 검토하는 대신, 아예 이 구조적 생성 방식을 박제한 새로운 '전용 스킬'을 그 자리에서 뚝딱 만들어낼 수 있다면 얼마나 편할까요?
다음 편에서는 구조적 접근법 자체를 스스로 스킬화하는 마법, generation-skill-creation 스킬의 내부 엔진을 들여다보겠습니다!
"구조를 지배하는 자가 결과물의 주권을 쥡니다. 그리고 최고의 구조는 다시 자동화된 스킬로 박제됩니다."
이 시리즈는 Cocrates Harness 프레임워크를 소개합니다. Cocrates는 소크라테스식 대화로 사용자가 주도권을 잡고 성장하도록 설계된 에이전트 하네스입니다.