Commands & Guardrails

한눈에 보기

Commands & Guardrails는 반복 작업을 시작하는 입구와 품질을 강제하는 안전장치를 함께 설명합니다. command가 작업을 열고, hook이 위험과 증거 누락을 검사하며, 실패 시 block, warn, review로 판단을 나눕니다.

• 핵심 질문: 반복 작업을 어떻게 표준화하고, 위험한 흐름은 어떻게 막을 것인가?
• 읽는 대상: slash command, hook, guardrail의 관계를 이해하려는 사람
• 연결 문서: Capabilities, Harness — Hooks & Gates, Evidence Dashboard

이 문서에서 확인할 것

• planning, implementation, verification, shipping command의 분류
• safety, evidence, quality, session, automation hook 카테고리
• HARD, SOFT, PROMOTION의 운영 차이

명령은 입구이고, hook은 안전장치다

Commands & Guardrails 메뉴는 실제 운영 표면을 보여줍니다. 명령은 반복 작업을 시작하는 입구이고, hook은 사람이 놓치기 쉬운 위험과 품질 조건을 자동으로 확인합니다.

flowchart TD
  A["User command"] --> B["Skill / workflow 실행"]
  B --> C["File / git / browser / docs 변경"]
  C --> D["Hook checks"]
  D --> E{"통과?"}
  E -->|yes| F["Evidence summary"]
  E -->|no| G["Block / Warn / Human review"]

Command 카테고리

카테고리	역할	예시
Planning	범위, 설계, 작업 단위 정리	/planning, /design-doc
Implementation	구현, 디버깅, 리팩터링	/tdd, /debugging, /refactoring
Verification	리뷰와 QA	/code-review, /qa-cycle
Shipping	커밋, PR, 동기화	/commit, /pr-create, /sync
Knowledge	기억과 문서화	/pkb, /pkb-capture, /logs
Evolution	회고와 자가 개선	/self-improve, /agent-retro

Hook 카테고리

mindmap
  root((Guardrails))
    Safety
      branch guard
      secret guard
      no force push
      destructive DB guard
    Evidence
      completion evidence
      browser QA
      build check
    Quality
      formatter
      type check
      API contract
    Session
      handoff
      recap
      context save
    Automation
      sync
      doctor
      eval

HARD와 SOFT

타입	역할	예시
HARD	조건 미충족 시 차단	secret commit, force push, protected branch
SOFT	경고 또는 맥락 주입	계획 누락, 증거 부족, 회고 권장
PROMOTION	반복 SOFT 위반을 HARD 후보로 승격	같은 실수 2회 이상 반복

운영 원칙

• 자주 쓰는 절차는 command로 만든다.
• 반복되는 실수는 hook 후보로 올린다.
• hook은 차단 이유와 복구 경로가 있어야 한다.
• 위험한 예외는 우회법이 아니라 승인 경로로 문서화한다.
• 명령 실행 결과는 Evidence Dashboard로 연결한다.

공개하지 않는 것

hook 구현 전체나 로컬 경로를 공개하지 않습니다. 대신 어떤 위험을 차단하는지, 어떤 범주의 검증이 있는지, 실패하면 어떤 판단으로 이어지는지만 공개합니다.