blackbox
개요
블랙박스는 항목의 비행 기록 장치입니다. 소유자가 승인한 변경 단위당 하나의 비요약 결정 기록을 저장합니다. 소유자가 실제로 말한 내용(원문 그대로), 문맥상 의미, 어시스턴트가 추천하고 구축한 내용, 그 이유, 각 선택을 이끈 증거, 그리고 어시스턴트가 잘못 이해한 부분을 포함합니다. 이 정보는 설명하는 콘텐츠에 고정되며 요청 시에만 읽힙니다. 목적은 추후 세션이 규칙의 기원을 다시 논쟁하지 않고 감사할 수 있도록 하는 것입니다.
블랙박스가 아닌 것:
- 기록(transcript)이 아닙니다. 선택을 요약하는 것이 아닙니다. 항목은 채팅 로그가 아닌 결정 추적(decision trail) 에서 작성됩니다. 소유자가 이해하는 데 도움이 되었지만 결정을 변경하지 않은 가르침, 비유, 우회로는 생략됩니다. 유지되는 내용은 전체가 보존됩니다.
- 소유자에 관한 일기가 아닙니다. 말해지고 결정된 내용을 기록할 뿐, 소유자가 누구인지는 기록하지 않습니다. 작업 스타일에 대한 관찰은 어시스턴트의 메모리에 속하며, 여기에 절대 기록하지 않습니다.
이 항목에 블랙박스가 있나요?
blackbox/README.md가 항목 옆(또는 저장소 루트)에 위치함 → 규칙이 적용됩니다. 해당 README와 가장 최근 항목을 읽은 후에만 항목을 작성하세요. 스키마는 README와 최신 항목에서 가져오며, 절대 임의로 만들지 마세요.- 마커가 없고 소유자가 도입을 요청함 → 부트스트랩: 이 스킬의 디렉토리에서
blackbox/README.md를 항목으로 복사하고, 항목 이름만 변경한 후 도입 자체를 첫 번째 항목으로 기록합니다. - 마커가 없고 이 세션에서 처음으로 사양/규칙/설계 문서를 편집하려는 경우 → 마커를 확인하세요. 없으면 한 번, 한 문장으로 도입을 제안한 후 소유자의 작업을 계속 진행하세요. 도입은 소유자의 결정입니다. 거절하면 저장소에 다시 묻지 않도록 메모리에 기록하세요.
도입 단위는 마커가 있는 디렉토리(스킬, 패키지, 또는 전체 저장소)입니다. 모든 저장소, 모든 병합 방식에 적용됩니다.
단위와 타이밍
- 소유자가 승인한 단위당 하나의 항목: 확인된 사양, 병합된 PR, 개정된 규칙. 커밋당, 대화 턴당이 아닙니다. 여러 커밋을 생성한 단위는 하나의 항목을 갖습니다.
- 결정이 이루어진 세션에서 작성됨. 원시 교환은 현재 컨텍스트에만 존재합니다. 세션이 종료되면 요약만 남고 원문 인용은 사라집니다. 단위가 길어지거나 여러 세션에 걸쳐 실행되는 경우, 초기에 초안을 저장하세요 —
Refs: pending, 소유자 인용 및 인덱스를 채워넣고 — 승인 시점에 마무리(blob 고정, 본문 완성)합니다. 초안은 재구성된 기억보다 낫습니다.
방법 (소유자 승인 단위별)
- 변경을 수행합니다.
- 결과를 콘텐츠별로 고정합니다. 변경된 각 파일에 대해 작업 트리에서
git hash-object <path>를 실행합니다. Blob SHA는 콘텐츠 주소 지정됩니다 — 동일한 바이트는 영원히 동일하게 해시되므로 고정은 squash, rebase, 모든 기록 재작성에서 살아남으며, 커밋 이전에 존재합니다. - 항목을 작성합니다
blackbox/YYYY-MM-DD-<slug>.md형식으로 아래와 같이: 본문을 가리키는 인덱스, 그 다음 원시 본문. - 변경과 함께 항목을 적용합니다 — 같은 커밋 또는 같은 PR에, 저장소가 일반적으로 병합하는 방식으로 병합합니다.
고정 확인: git hash-object <path>를 실행하고 비교합니다. 고정된 상태 검색: git log --find-object=<sha> 또는 GitHub blobs API.
읽기 규칙: 항목에 대한 정상 작업 중에는 blackbox/를 절대 로드하지 마세요. 출처 질문이 있을 때만 읽습니다.
항목 형식
# YYYY-MM-DD — <제목>
Refs: <경로> @ blob <sha> (변경된 파일당 한 줄)
Decisions: <결정> <가중치> [→ <새 가중치>, §… 참조] · …
Reversals: §… · §… (또는: 없음)
Owner caught: §… · … (또는: 없음)
Declined: §… · … (또는: 없음)
Evidence: <명령어 / 숫자 / 링크> · …
Understanding: §… (또는: 해당 없음)
---
<인덱스가 가리키는 § 제목이 있는 원시 본문>
인덱스 줄은 본문을 가리킵니다. 본문을 대체하지 않습니다.
- Decisions — 단위가 포함하는 모든 결정과 어시스턴트가 질문할 때 할당한 가중치(🔴 지금 결정해야 함 · 🟡 결정, 수정 가능 · 🟢 권장 사항 수용). 가중치가 나중에 변경된 경우, 그 사실과 이유를 지시하세요. 시간이 지남에 따라 이 줄은 소유자가 자신의 숙고를 결정이 받아야 할 가중치에 대해 감사하는 방법입니다.
- Reversals — 어시스턴트가 주장했다가 나중에 철회하거나 수정한 모든 것: 잘못된 주장, 측정에 의해 뒤집힌 권장 사항, 묻지 않고 내린 결정.
없음은 유효한 값이며 명시적으로 작성해야 합니다. - Owner caught — 소유자가 발견한 불일치 또는 결함(잘못된 수, 누락된 항목, 구조적 버그). 어시스턴트뿐만 아니라 소유자의 감사.
- Declined — 의도적으로 채택하지 않은 옵션, 도구 기본값 또는 외부 권장 사항. 이유는 본문에 있습니다.
- Evidence — 결정할 때 실제로 본 내용: 실행한 명령어, 생성된 숫자, 표시된 페이지 또는 파일. 재현(reproduction) 을 기록하세요. 스크린샷이 아닌 다이어그램은 명령어에서 재생성됩니다.
- Understanding — 소유자가 완전히 이해하지 못했다고 말하면서 승인한 경우, 그 진술과 나중에 다시 설명해야 할 내용.
언어
- 본문: 영어, 저장소의 문서 언어와 관계없이.
- 소유자 입력: 원문 그대로, 그 다음 영어 재작성. 먼저
>인용으로 원문을 정확히 입력한 대로(오타, 약어,ㅇ등 모두 포함) 작성합니다. 그 다음 재작성: 내용이 완전하고, 형태가 자연스럽고, 독립적입니다(다른 컨텍스트 없이도 이해할 수 있음). 원문은 증거입니다 — 결정을 변경한 오타는 여기서만 찾을 수 있습니다. 재작성은 당시 어시스턴트의 해석입니다 — 둘이 일치하지 않으면, 항목은 이미 결함을 기록한 것입니다. - 어시스턴트 응답, 추론 및 내부 처리: 영어, 결정에 영향을 미치는 모든 내용에 대해 완전한 형식.
> ㅇ다음에소유자가 옵션 (a)를 승인했습니다.는 완전한 기록입니다. 덧붙이지 마세요.
엄격한 형식
| 규칙 | 이렇게 하지 마세요 |
|---|---|
| 소유자 입력 = 원문 인용 및 영어 재작성 | 원문만(컨텍스트 없이 읽을 수 없음), 재작성만(증거 손실), 또는 한 줄 요약 |
상단에 인덱스, 아래에 원시 본문, 인덱스 줄이 § 제목을 가리킴 | 요약하는 인덱스, 인덱스가 없는 본문, 한 줄로 채워진 섹션 |
| 결정 추적에서 작성된 본문 | 결정을 변경하지 않은 가르침, 비유, 우회로 |
Reversals:가 없음으로도 존재 | 잘된 것만 나열하는 항목 |
Refs: = 파일별 blob SHA (git hash-object) | 앵커로 커밋 또는 PR 번호 사용 — 기록 재작성이 앵커를 무효화함 |
| 항목이 변경과 같은 커밋 또는 PR에 적용됨 | "나중에" 후속 PR |
| README 및 최신 항목의 스키마 | 발명된 형식 |
위험 신호
Refs:줄이 없거나, blob 대신 커밋 또는 PR을 명명하는Refs:>원문 인용이 없거나, 인용 뒤에 재작성이 없는 소유자 입력Reversals:줄이 전혀 없음- 요약처럼 읽히는 인덱스 줄(포인터가 아닌)
- 독자에게 개념을 설명하는 본문(결정된 내용을 기록하지 않음)
- 항목 없이 병합된 변경
- 기록하는 결정 이후 세션에서 작성된 항목(불가피한 경우 항목에 명시)
출처
blackbox/는 이 항목에 대한 전체 결정 기록을 보유합니다 — 소유자 입력(원문 + 영어 재작성), 어시스턴트 추론, 증거, 반전, 승인된 변경당 콘텐츠 고정. 규칙이 존재하는 이유나 소유자가 원래 요청한 내용을 조사할 때만 읽으세요. 정상 사용 중에는 절대 로드하지 마세요.