wellwelwel/blue-spec

Blue Spec 명령 시뮬레이션하기

이 스킬은 명령을 시뮬레이션하는 것이 생각보다 쉽게 잘못되어 사용자의 시간과 신뢰를 낭비할 수 있기 때문에 존재합니다. 수많은 시행착오 끝에 네 가지 불가침 규칙과 하나의 방법론이 도출되었습니다. 이를 정확히 따르세요.

사용자가 /bluespec.* 명령(charter, detect, plan, harden, verify) 중 하나를 "시뮬레이션", "데모", "실제로 보여줘", "실행", 또는 "실제 동작"을 요청하거나, 명령을 실제로 적용하기 전에 어떻게 동작하는지 미리 보려고 할 때 이 스킬을 사용하세요.

시작하기 전에 (필수)

시뮬레이션을 시작하거나, 시나리오를 구성하거나, 픽스처를 복사하기 전에 다음 두 가지가 반드시 순서대로 해결되어야 합니다:

1. 사용자는 어떤 Blue Spec 명령을 시뮬레이션할지 알려줘야 합니다. 이는 필수이며, 절대 추측하거나 선택하지 마세요. 사용자가 명령(charter, detect, plan, harden, 또는 verify)을 지정하지 않았다면, 다른 작업을 하기 전에 먼저 어떤 명령인지 물어보세요. 두 개 이상을 지정했다면, 실행할 순서를 확인하세요.
2. 그런 다음 사용 가능한 픽스처(fixture)를 번호 목록으로 제시하고 사용자가 선택하도록 합니다. 명령이 정해지면 .claude/skills/simulate/fixtures/ 디렉토리에서 사용 가능한 픽스처를 각 시나리오를 한 줄로 설명하여 번호 목록으로 보여주고, 사용자에게 번호로 하나를 선택해 달라고 요청하세요. 자동으로 특정 픽스처를 선택하지 마세요. 픽스처가 하나만 있더라도, 그것을 제시하고 사용하기 전에 확인을 받으세요. 어떤 픽스처도 명령에 적합하지 않다면, 그렇게 말하고 새 픽스처를 추가하겠다고 제안하세요 (픽스처 섹션 참고).

명령이 지정되고 픽스처가 선택된 후에만 아래의 규칙과 방법을 진행합니다.

이 스킬이 존재하는 이유 (먼저 읽으세요)

Blue Spec 명령은 독립 실행형 프로그램이 아닙니다. 이것은 AI 에이전트에게 보안 작업의 한 단계를 수행하는 방법을 알려주는 명령어 파일(spec/commands/bluespec.<phase>.md, 에이전트가 읽는 스킬로 스캐폴딩됨)입니다. "명령을 실행한다"는 것은 에이전트가 그 지침을 따르는 것을 의미합니다. 에이전트와 독립적으로 결정적인 결과를 내놓는 바이너리 같은 것은 없습니다. 따라서 "시뮬레이션"은 에이전트가 실제 시나리오를 대상으로 명령의 단계를 실제로 수행하면서 그 작업 과정을 보여주는 것입니다.

피해야 할 실패 패턴: 명령이 출력할 것이라고 상상하는 내용을 서술하고, 마치 터미널 출력처럼 보이게 포맷팅한 다음, 실제로 실행된 것처럼 제시하는 것입니다. 그것은 연극일 뿐입니다. 사용자는 만들어진 출력과 실제 출력을 구분할 수 없으며, 당연히 그것을 "허구"라고 부를 것입니다. 아래의 모든 내용은 시뮬레이션이 실제로 수행되고 사용자가 확인할 수 있도록 만들기 위해 설계된 것이지, 쇼를 위한 것이 아닙니다.

네 가지 불가침 규칙

규칙 1: ./temp 디렉토리 아래에서 시나리오 실행

시뮬레이션이 다루는 모든 것(픽스처, 단계가 생성하는 .bluespec/memory/ 아티팩트, 모든 입력)을 시스템 /tmp가 아닌 저장소 루트의 ./temp 디렉토리 안에 구축하세요.

• /tmp는 사용자에게 보이지 않습니다: 에디터에서 해당 파일을 열 수 없으므로, 거기서 하는 모든 작업은 "저를 믿으세요"가 됩니다. ./temp는 사용자의 작업 공간에 있으며, 열고 검사할 수 있습니다.
• ./temp는 git에 무시되므로(.gitignore 처리), 시뮬레이션이 커밋을 오염시키지 않습니다.
• 사용자가 작업을 마치면 ./temp를 정리하거나, 검사할 수 있도록 남겨두되, 먼저 사용자에게 물어보세요.

픽스처: 모든 시뮬레이션은 하나의 픽스처에서 시작

중립적인 샘플 프로젝트는 이 스킬 옆에 제공되며, 각각 .claude/skills/simulate/fixtures/<name>/ 디렉토리에 있습니다. 명령이 필요로 하는 시나리오에 맞는 픽스처를 선택하거나, 새 픽스처를 추가하세요 (아래 참고). 모든 픽스처는 작고 실제적인 프로젝트로, **중립적인 쌍(neutral pairs)**으로 의도적으로 견고한 코드와 취약한 코드를 모두 포함하고 있어 명령이 레이블을 읽는 것이 아닌 코드를 분석하도록 합니다.

사용 가능한 픽스처:

• image-upload-service: 이미지 업로드를 받고 다시 제공하는 작은 ESM HTTP 서비스입니다.
• template-toolkit: 템플릿 렌더링 및 텍스트 파싱을 위한, 배포 가능한 ESM npm 패키지(라이브러리 + tmpl CLI)입니다.

항상 하나의 픽스처를 그대로 ./temp 디렉토리로 복사하여 시뮬레이션을 시작하세요. 만약 ./temp가 이미 존재하고 비어있지 않다면, 먼저 비운 후 각 실행이 깨끗하게 시작되도록 하세요 (<name>을 선택한 픽스처 이름으로 바꾸세요):

rm -rf ./temp && mkdir -p ./temp
cp -R .claude/skills/simulate/fixtures/<name>/. ./temp/

그런 다음 규칙 4에 따라 상위 단계를 실제로 실행하여 ./temp에 체인을 구축하세요. 명령이 읽는 .bluespec/memory/*.md 아티팩트는 직접 작성된 것이 아니라 해당 단계 자체에 의해 생성되어야 합니다. 규칙 3에 따라 사양을 문자 그대로 따르며 ./temp를 대상으로 명령의 단계를 실행하고, 규칙 2에 따라 각 단계의 출력을 보여주세요.

픽스처를 추가하려면 .claude/skills/simulate/fixtures/<new-name>/ 디렉토리를 자체 package.json을 가진 작고 실제적인 프로젝트로 만들고, 견고한 코드와 취약한 코드를 중립적인 쌍으로 유지하며, 내용을 암시하는 주석이나 이름을 추가하지 마세요. 그리고 위 목록에 추가하세요. 현재 픽스처가 다루지 않는 자료(다른 언어나 스택, 비밀 처리, 인증, 데이터베이스 등)가 명령에 필요할 때 추가하세요.

규칙 2: 프롬프트와 응답을 채팅 메시지에 펜스 코드 블록으로 표시

이 규칙을 배우는 데 가장 오랜 시간이 걸렸습니다. 도구(Bash, Read)를 실행할 때, 사용자 인터페이스는 해당 도구의 IN과 OUT에 대한 잘린 미리보기를 보여줍니다. 얼마나 많이 보여줄지는 통제할 수 없으며, 대부분 잘려서 보입니다. 만약 주장을 뒷받침하는 증거가 도구 호출의 출력 안에만 있다면, 사용자는 그것을 볼 수 없고, 그것을 설명하는 어떤 문장도 허구처럼 읽힐 것입니다.

따라서:

• 도구를 실행한 후, 관련 원시 출력을 펜스 코드 블록(삼중 백틱 ```)으로 복사하여 일반 채팅 메시지에 넣으세요. 펜스 블록은 모든 인터페이스에서 완전하고 동일하게 렌더링됩니다. 이것이 사용자가 의미하는 "노란 글씨(yellow letters)", 즉 마크다운 코드 블록입니다.
• 명령의 프롬프트와 상호작용(즉, /bluespec.<phase>가 실행될 때 보여주는 단계별 진행, 범위 결정, 판정 등)도 펜스 코드 블록에 대화록처럼 넣으세요.
• 절대 도구 호출을 가리키며 "위 출력이 X를 보여줍니다"라고 쓰지 마세요. 사용자가 전체를 읽을 수 있도록 당신이 붙여넣은 펜스 블록을 가리키세요.
• 대화록에 있는 숫자나 줄이 실제 실행에서 나온 것이라면, 당신이 붙여넣은 원시 출력과 일치해야 합니다. 붙여넣은 원시 출력으로 뒷받침되지 않는 대화록 줄을 작성한다면, 그것은 지어내는 것이니 중단하세요.

신뢰할 수 있는 패턴: 명령을 실행하고, 원시 출력을 ./temp 아래 파일(예: ./temp/run.log)로 리디렉션한 다음, 해당 파일을 Read하고 (Read 결과는 전체가 표시됨) 그 내용을 펜스 블록에 붙여넣으세요. 사용자는 또한 ./temp/run.log를 열어 확인할 수 있습니다.

마지막에 한꺼번에 모아서 보여주지 말고, 진행하면서 바로바로 보여주세요. 트리거는 단계별입니다: 단계가 사용자가 봐야 할 무언가(읽은 입력, 대화록, 작성한 아티팩트)를 생성하는 즉시, 다음 단계 전에 같은 메시지의 펜스 블록에 붙여넣으세요. 만약 다음 단계나 수정을 시작하려고 하는데 이전 단계의 출력이 아직 화면에 없다면, 멈추고 먼저 붙여넣으세요. 사용자가 명령의 출력을 보여달라고 상기시켜야 한다면, 이미 규칙을 위반한 것입니다.

규칙 3: 당신이 명령이므로, 그 사양을 문자 그대로 따르세요

"명령 실행"은 당신이 spec/commands/bluespec.<phase>.md를 단계별로 실행하는 것이지, 당신만의 방식으로 단계를 수행하고 그것을 명령이라고 부르는 것이 아닙니다.

• 먼저 해당 사양을 열고 단일 진실 공급원으로 취급하세요. 순서대로 단계를 따르세요. 기억이나 이 스킬의 요약에서 단계를 실행하지 마세요.
• 사양이 요구하는 모든 확인 중단(confirmation stop)을 실제로 수행하세요. harden은 코드를 편집하기 전에 반드시 확인을 받아야 하며, 전체 detect 스캔은 토큰을 많이 사용하기 때문에 확인이 필요합니다. 사양이 제시하라고 하는 내용을 대화록 블록에 제시하고 기다리세요. 확인 없이 코드를 편집하거나 중단된 단계를 실행하지 마세요.
• 범위, 판정, 수정, 우선순위, 발견 사항을 실제 시나리오를 바탕으로 사양의 단계가 결정하는 방식으로 결정하세요. 만약 출력의 한 줄을 정당화하는 사양 단계를 가리킬 수 없다면, 당신은 당신 자신으로 행동하고 있는 것이므로, 중단하고 사양을 따르세요.

규칙 4: 각 단계의 입력은 당신이 아닌 이전 단계 실행에서 나와야 함

체인은 charter → detect → plan → harden → verify 순서이며, 각 단계는 이전 단계가 작성한 내용을 읽습니다. 당신이 예상하는 답변이 이미 기록된 하위 단계 아티팩트(예를 들어, verify가 확인하거나 잡아내길 원하는 것을 정확히 기록한 harden.md)를 직접 작성하는 것은 실패입니다: 그러면 하위 단계는 실제 상황이 아닌 당신의 예측을 대상으로 테스트되므로, 당신이 놓친 것을 그대로 놓치게 됩니다.

• 모든 상위 단계 아티팩트를 해당 단계를 실행하여 생성하고, 규칙 2에 따라 그 과정을 보여주세요. verify를 데모하려면, detect(코드 읽기)를 실행하고, plan(detect.md 읽기)을 실행하고, harden(plan.md 읽기, 코드 편집)을 실행하세요. 사용자가 중간 체인부터 시작하더라도, 이렇게 순서대로 누락된 아티팩트를 구축하세요.
• 아티팩트가 실제 실행 결과를 말하게 하세요. Partial, Blocked, 예상치 못한 발견 등 그대로 포함시켜야 합니다. 의심스러울 정도로 깔끔한 아티팩트는 이 규칙이 위반되었음을 알려주는 신호입니다.
• 의도적으로 시나리오를 다르게 만드는 것은 괜찮습니다(harden이 모든 것을 적용한 후, 코드를 되돌려서 verify가 변경을 잡아내야 하도록 하는 경우 등). 하지만 변경 사항을 시각적으로 도입하고(표시된 도구 호출에서 되돌리기, 실제 아티팩트 유지), 실행에서 생성되지 않은 기록을 직접 작성하지 마세요.

방법론: 단계별

각 단계는 이전 단계를 읽고 하나의 아티팩트를 씁니다. 이 체인을 알고 절대 깨뜨리지 마세요:

단계	읽는 대상	쓰는 대상
charter	프로젝트 컨텍스트	.bluespec/memory/charter.md
detect	코드	.bluespec/memory/detect.md
plan	오직 detect.md만, 절대 코드는 읽지 않음	.bluespec/memory/plan.md
harden	오직 plan.md + 헌장(charter), 그리고 사용자 코드를 편집	.bluespec/memory/harden.md
verify	harden.md 및 코드를 읽어 기록과 실제를 대조하고, 아무것도 변경하지 않음	.bluespec/memory/verify.md

그런 다음, 시뮬레이션하는 명령에 대해:

1. 픽스처를 그대로 ./temp에 복사합니다 (규칙 1).
2. 각 상위 단계를 순서대로 ./temp에 대해 실행하여 체인을 구축합니다 (규칙 4).
3. 대상 단계를 해당 spec/commands/bluespec.<phase>.md 사양에 따라 문자 그대로 실행합니다 (규칙 3).
4. 진행하면서 모든 입력, 대화록, 아티팩트를 펜스 블록으로 보여줍니다 (규칙 2). 각 출력 아티팩트를 실제 파일로 작성한 다음, Read하여 보여줍니다.

무엇이든 제시하기 전에 정직성 확인

• 이것이 실제로 실행된 것인가, 아니면 내가 무엇이 일어날지 생각나는 대로 입력하고 있는가?
• 모든 대화록 줄이 내가 붙여넣은 원시 출력이나 사용자가 열 수 있는 ./temp 파일(잘린 도구 호출이 아닌)로 뒷받침되는가? (규칙 2)
• 지금까지 각 단계의 출력을 이미 붙여넣어서 사용자가 절대 물어볼 필요가 없게 했는가? (규칙 2)
• 내가 아닌 명령으로서 행동하기 위해 각 단계의 사양과 확인 중단을 따랐는가? (규칙 3)
• 각 상위 단계 아티팩트가 내가 원하는 결과를 직접 작성한 것이 아니라, 해당 단계를 실행하여 나온 것인가? (규칙 4)
• 시나리오가 /tmp에 숨겨지지 않고 ./temp 아래에 있는가? (규칙 1)

만약 하나라도 '아니오'라면, 보내기 전에 수정하세요. 사용자는 정제된 허구보다는 소박하지만 실제적인 출력을 보는 것을 선호합니다.