6기둥으로 다시 읽는 superpowers

Jesse Vincent의 obra/superpowers는 문서형 하네스를 실제로 운영 중인 보기 드문 오픈소스 사례다. SKILL.md 8개를 직접 열어 ROLE · GOAL · FORBID · OUTPUT · EXAMPLE · CHECK 6기둥에 매핑해 두면, 내 규칙서를 짤 때 어느 칸을 비워 두고 있는지 한눈에 보인다. 여기에 더해 hooks/ 디렉토리가 markdown 밖에서 한 겹을 더 잠그는데, 이 레포가 "문서형 + 시스템 레벨" 두 층을 어떻게 합쳤는지도 함께 본다.

01 · 스캐폴딩6기둥 — 마크다운 하네스의 골격

아래 6칸이 한 SKILL.md 안에 모두 채워져 있어야 AI가 매번 같은 결과를 낸다. 한 칸이라도 비면 그 자리에서 추측이 끼어든다.

02 · 매핑superpowers의 어느 장치가 어느 기둥인가

각 기둥이 superpowers 레포 안에서 어떤 구문 장치로 구현되어 있는지 정리한다. 같은 기둥이 여러 곳에서 보강되는 것도 패턴이다.

기둥	superpowers의 구문 장치	역할
1 · ROLE	YAML frontmatter name + description "When to Use" 섹션	스킬이 언제 호출되어야 하는지를 한 줄로 잠근다. description이 곧 트리거 조건문 역할을 한다.
2 · GOAL	"Overview" 첫 문장 "Core principle:" 한 줄	완료 시점에 남을 단 한 문장을 굵게 박아 둔다. 본문이 흐트러져도 이 한 줄이 척추다.
3 · FORBID	"The Iron Law" 박스 "<HARD-GATE>" / "<EXTREMELY-IMPORTANT>" "Red Flags - STOP" 목록 "Rationalization Prevention" 표	가장 강한 칸. 같은 금지를 4~5개 다른 표현으로 중복 배치해 AI가 빠져나갈 합리화 통로를 모두 막는다.
4 · OUTPUT	"Plan Document Header" 템플릿 저장 경로 규칙: docs/superpowers/plans/YYYY-MM-DD-<name>.md "Task Structure" 마크다운 견본	산출물의 파일명·헤더·섹션 순서까지 못 박는다. 빈칸을 채우기만 하면 같은 모양이 나오게 만든다.
5 · EXAMPLE	<Good> / <Bad> 코드 블록 "Common Failures" 표 (Claim → Requires → Not Sufficient) RED-GREEN-REFACTOR 견본 코드	금지/요구를 추상으로 두지 않고, 통과 견본과 탈락 견본을 짝으로 보여 톤까지 학습시킨다.
6 · CHECK	"Checklist" (번호 매긴 단계) "The Gate Function" (IDENTIFY → RUN → READ → VERIFY) "Phase 1~4" 강제 순서 verification-before-completion 스킬 통째	출력 직후 사람이 — 또는 다른 subagent가 — 한 줄씩 확인할 항목. 단계 사이에 다이아몬드 분기를 둬 통과 못 하면 앞으로 못 간다.

장치별 분포 — 어느 스킬이 그 장치를 실제로 쓰는가

14개 SKILL.md를 직접 grep으로 훑어 각 장치가 등장하는 파일을 모았다. 같은 기둥이라도 장치마다 채택률이 다르다 — frontmatter description은 모든 스킬에 있고, Iron Law는 4개만, Rationalization Prevention 표는 같은 그 4개에 같이 붙는다. 어떤 장치가 어떤 스킬과 짝지어지는지 보면 superpowers 작자의 채택 기준이 보인다.

기둥 · 장치	채택 스킬	관찰
1 · frontmatter description	14개 전부 (표준 골격)	예외 없음. "Use when ~ before ~" 패턴이 ROLE 기본 트리거.
1 · "When to Use" 별도 섹션	dispatching-parallel-agents, subagent-driven-development, systematic-debugging, test-driven-development, writing-skills	호출 조건이 복잡한 스킬에만 별도 섹션을 추가. 단순 스킬은 frontmatter 한 줄로 끝.
2 · "Core principle:" 한 줄	10개 — dispatching-parallel-agents, finishing-a-development-branch, receiving-code-review, requesting-code-review, subagent-driven-development, systematic-debugging, test-driven-development, using-git-worktrees, verification-before-completion, writing-skills	GOAL 한 줄을 명시적으로 라벨링한 패턴. 14개 중 10개니 사실상 표준이다.
3 · "The Iron Law"	4개만 — systematic-debugging, test-driven-development, verification-before-completion, writing-skills	가장 강한 금지 장치. 모두 "절대 ~ 없이 ~ 금지" 단언형. 이 4개는 모두 Rationalization Prevention 표를 같이 쓴다.
3 · <HARD-GATE> 태그	brainstorming 1개	"디자인 승인 전까지 구현 스킬 호출 금지"라는 단일 게이트에만 쓰임. 희소 장치.
3 · <EXTREMELY_IMPORTANT> 태그	using-superpowers 1개 (+ hook 주입 래퍼)	메타 스킬 1개에만 쓰임. hook이 매 세션 시작 때 같은 태그로 본문을 다시 감싸 이중 잠금.
3 · "Red Flags" 목록	9개 — finishing-a-development-branch, requesting-code-review, subagent-driven-development, systematic-debugging, test-driven-development, using-git-worktrees, using-superpowers, verification-before-completion, writing-skills	가장 널리 쓰이는 FORBID 장치. "이런 말이 나오면 STOP"의 트리거 문구 모음.
3 · "Rationalization Prevention" 표	4개 — systematic-debugging, test-driven-development, verification-before-completion, writing-skills	Iron Law를 가진 스킬과 정확히 동일한 4개. 두 장치는 항상 짝으로 등장한다.
3 · "Anti-Patterns" 섹션	brainstorming, test-driven-development, writing-skills	"이건 너무 단순해서 ~ 필요 없음" 같은 회피 합리화를 명시적으로 잘라낸다.
4 · 저장 경로 + 헤더 템플릿	brainstorming (docs/superpowers/specs/), writing-plans (docs/superpowers/plans/), subagent-driven-development (output flow 정의)	산출물이 파일로 떨어지는 스킬에만 쓰임. 경로 형식까지 못 박는 게 공통.
4 · TodoWrite 강제 등록	executing-plans, subagent-driven-development, using-superpowers, writing-skills	단계 진행을 외부 도구(TodoWrite)에 위임해 OUTPUT을 상태 머신으로 만든다.
5 · <Good> / <Bad> 짝 코드	test-driven-development, writing-skills	코드 예시가 핵심인 스킬에서만 통과/탈락 견본을 짝으로 제시.
5 · "Common Failures" 표	verification-before-completion 1개	Claim/Requires/Not Sufficient 3열 7행 그리드. 이 스킬만의 시그니처 장치.
5 · Pressure scenarios (TDD mapping)	writing-skills 1개 (메타)	"스킬 자체를 TDD로 만든다"는 메타 매핑 표. 스킬 작성 가이드 전용.
6 · 번호 매긴 "Checklist"	brainstorming, test-driven-development, writing-skills	선형 단계 검수. 스킬당 5~9단계.
6 · "The Gate Function"	verification-before-completion 1개	IDENTIFY → RUN → READ → VERIFY → THEN claim. 5단계 모두 통과해야 "완료" 가능.
6 · "Phase 1~N" 강제 순서	systematic-debugging 1개	4 Phase 순차 통과. Phase 1만 sub-check 7단계.
6 · graphviz digraph 분기	6개 — brainstorming, dispatching-parallel-agents, subagent-driven-development, test-driven-development, using-superpowers, writing-skills	CHECK를 다이아몬드 분기 그래프로 그린 스킬들. 선형 체크리스트보다 우회를 더 잘 막는다.
6 · "Quick Reference" 요약	finishing-a-development-branch, systematic-debugging, using-git-worktrees, writing-skills	본문이 긴 스킬은 끝에 한 화면짜리 빠른 참조를 같이 넣는다.

읽는 법: 같은 칼럼에 여러 스킬이 모이면 그 장치가 사실상 표준이다(예: Red Flags 9/14, Core principle 10/14). 하나만 있는 장치는 시그니처다(예: Common Failures 표 = verification-before-completion 전용). 내 규칙서를 짤 때, 표준 장치는 기본값으로 들고 가고 시그니처 장치는 그 스킬의 목적과 같을 때만 빌려온다.

03 · 표준 프론트매터스킬 1개의 최소 골격

모든 SKILL.md가 공유하는 머리 모양. description은 곧 ROLE이 된다 — "Use when ~ before ~" 패턴으로 호출 조건과 시점을 한 줄에 묶는다.

---
name: verification-before-completion
description: Use when about to claim work is complete, fixed, or passing,
             before committing or creating PRs — requires running verification
             commands and confirming output before making any success claims;
             evidence before assertions always
---

# Verification Before Completion

## Overview            ← 2 · GOAL (한 줄)
## The Iron Law         ← 3 · FORBID (가장 굵게)
## The Gate Function    ← 6 · CHECK (단계화)
## Common Failures      ← 5 · EXAMPLE (통과/탈락 표)
## Red Flags - STOP     ← 3 · FORBID 보강
## Key Patterns         ← 4 · OUTPUT (응답 견본)

이 6칸이 한 파일 안에 모두 있고, 같은 기둥이 두세 군데에서 보강되는 게 superpowers의 일관된 패턴이다.

04 · 8개 스킬 해부각 스킬은 어느 기둥이 강한가

스킬마다 6기둥의 무게중심이 다르다. 어떤 스킬은 FORBID로 시작해 CHECK로 닫고, 어떤 스킬은 OUTPUT 템플릿이 본체다. 내가 짤 규칙서가 어느 종류인지 미리 정해야 한다.

05 · Hook 경계markdown으로 못 잠그는 칸을 시스템이 잠근다

SKILL.md를 아무리 빈틈없이 적어도 "AI가 그 파일을 매번 열어 본다"는 보장은 markdown 안에 없다. obra/superpowers는 이 한계를 hooks/ 디렉토리로 메운다 — 6기둥이 문서 안 잠금이라면, hook은 그 바깥에서 OS·플러그인 런타임이 거는 잠금이다.

레포 안에서 hook이 사는 자리

hooks/hooks.json은 한 가지 이벤트만 등록한다. 단순하지만 효과가 크다.

// hooks/hooks.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

세션이 시작될 때(startup), /clear로 컨텍스트를 비울 때, 자동 압축이 일어날 때(compact) — 세 시점 모두에서 session-start 스크립트가 실행된다. 그 스크립트가 하는 일은 한 줄로 줄이면: skills/using-superpowers/SKILL.md 전문을 읽어 additionalContext로 모델에 강제 주입한다.

주입되는 컨텍스트의 모양

모델이 받는 첫 메시지에는 다음과 같은 블록이 강제로 끼어 있다.

<EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' skill -
your introduction to using skills. For all other skills, use the 'Skill' tool:**

{{ using-superpowers/SKILL.md 전문 }}

</EXTREMELY_IMPORTANT>

즉 사용자가 입을 떼기 전에 using-superpowers 한 개 스킬은 이미 컨텍스트 안에 들어와 있고, 그 안에는 "어떤 메시지든 받기 전에 Skill 도구로 다른 스킬부터 탐색하라"는 메타 규칙이 적혀 있다. 나머지 7개 스킬은 markdown 잠금만 받지만, 이 1개 스킬은 hook 잠금까지 이중으로 받는다.

6기둥과 어떻게 짝지어지나

기둥	markdown 안 잠금	hook이 더하는 잠금
1 · ROLE	frontmatter description의 "Use when ~ before ~"	매 세션 시작 시 무조건 호출. matcher로 트리거 시점을 OS 이벤트에 묶는다 — 모델이 "지금은 호출 안 해도 되겠지"로 빠져나갈 통로가 사라진다.
3 · FORBID	Iron Law / HARD-GATE / Red Flags 4겹 텍스트	<EXTREMELY_IMPORTANT> 래퍼로 시스템 레벨 우선순위 부여. 사용자 첫 입력보다 먼저 들어가기 때문에 "사용자가 다른 걸 시켰으니 건너뛴다" 합리화가 막힌다.
6 · CHECK	"Checklist" / "Gate Function" 단계 텍스트	사람이 안 끼고도 매번 실행되는 자동 게이트. /clear·compact 후에도 재주입되어 컨텍스트 유실로 인한 우회가 차단된다.

Polyglot .cmd 래퍼 — 한 진입점, 세 OS

run-hook.cmd는 CMD와 bash 양쪽에서 동시에 유효한 polyglot 스크립트다. Windows에서는 CMD가 :를 라벨로 읽어 bash 영역을 건너뛰고, macOS·Linux에서는 같은 줄이 heredoc 시작이 되어 CMD 영역을 무시한다. OS별로 다른 진입점을 따로 등록할 필요 없이 hooks.json 한 줄로 세 플랫폼을 덮는다. 문서로 잠그는 것과 별개로, "내 플러그인을 받은 모든 사용자 환경에서 동일하게 작동"이라는 시스템 수준 보장을 hook이 책임진다.

여기서 가져갈 것

markdown으로 6기둥을 다 채워도 "AI가 그 파일을 읽었나"는 여전히 확률 게임이다. superpowers는 SessionStart hook 한 개로 그 확률을 1.0으로 만든다. 내 규칙서에서 이 패턴이 필요한 자리는 두 군데다 — (1) 메타 스킬(다른 스킬들의 호출 조건을 정의하는 스킬)과 (2) 절대로 누락되면 안 되는 검수 게이트. 이 둘은 markdown만으로는 부족하니, 4장 분업형 하네스에서 hook·subagent·외부 검증 도구로 한 겹을 더 얹는다.

06 · 핵심 패턴superpowers에서 가져갈 5가지

레포 전체를 가로지르는 작법 규칙. 내 규칙서를 짤 때 그대로 차용해도 좋다.

• 같은 금지를 4겹으로 박는다 Iron Law(굵게) → HARD-GATE(태그) → Red Flags 목록 → Rationalization Prevention 표. 한 가지 FORBID를 네 가지 다른 표현으로 중복 배치해 AI가 새어 나갈 구멍을 모두 막는다. 한 번만 적은 금지는 지켜지지 않는다.
• frontmatter의 description이 곧 ROLE이다 "Use when X, before Y" 패턴. 호출 조건(when)과 시점(before)을 한 줄에 묶어 두면, 스킬 자체가 자기 트리거를 정의한다. 별도 라우터가 필요 없다.
• CHECK는 다이아몬드 분기로 그린다 모든 주요 스킬이 graphviz dot 문법으로 작성된 분기 그래프를 본문에 포함한다. 선형 체크리스트보다 분기형 검수가 통과 못 하면 앞으로 못 가게 만든다.
• OUTPUT은 파일명까지 못 박는다 docs/superpowers/plans/YYYY-MM-DD-<name>.md 처럼 저장 경로·파일명 형식·헤더 마크다운을 통째로 견본화. 빈칸 채우기 게임으로 만들어야 매번 같은 결과가 나온다.
• EXAMPLE은 통과/탈락 2열로 짝짓는다 <Good>/<Bad> 코드, Common Failures 표(Claim/Requires/Not Sufficient), TDD Mapping 표. 한쪽만 보여 주면 톤이 안 잡힌다. 짝을 보여 줘야 경계가 학습된다.

07 · 빈칸 체크내 규칙서에 적용해 보기

지금 쓰고 있는 SKILL.md를 6기둥에 비춰 본다. 한 칸이라도 비었다면 그 자리에서 AI가 매번 다르게 답한다.

기둥	이 칸이 비면 일어나는 일	최소 채울 분량
1 · ROLE	스킬이 엉뚱한 상황에서 호출되거나, 호출되어야 할 때 호출 안 됨	"Use when X, before Y" 한 줄
2 · GOAL	중간에 길을 잃고 본문이 산만해짐. 사용자가 "그래서 뭘 받았지?" 됨	"Core principle:" 한 문장
3 · FORBID	AI가 합리화 통로로 빠져나감. "시간 없으니 이번엔 건너뛸게요"	Iron Law 1개 + Rationalization 표 3행
4 · OUTPUT	매번 다른 구조·다른 파일명·다른 섹션. 후속 도구가 못 받음	저장 경로 + 헤더 마크다운 견본
5 · EXAMPLE	형식은 맞지만 톤이 매번 다름. 산출물이 같은 카테고리로 안 묶임	<Good>/<Bad> 각 1개
6 · CHECK	"완료했습니다"가 거짓말이 됨. 다음 단계로 미검증 통과	3~5단계 게이트 + 다이아몬드 분기

실습 연결: 2003-4-1-harness-writing-practice.md에서 본인 규칙서를 작성할 때, 이 표를 옆에 펴 두고 6칸을 모두 채웠는지 단계 종료마다 확인한다. 빈칸은 다음 클립의 분업형 하네스로 넘기는 게 아니라, markdown으로 잠글 수 있는 만큼 잠그고 한계만 4장으로 넘긴다.