research-log은(는) 무엇을 하나요?
엔지니어가 나중에 이야기하는 방식으로 연구를 문서화합니다. 측정값을 기반으로 한 스토리, 재구현이 가능할 정도로 정밀한 스펙, 수치가 포함된 검증 기록, 그리고 아직 알려지지 않은 내용에 대한 정직한 목록을 하나의 자체 포함 HTML 파일(CSS와 이미지가 내장되어 외부 자산이 필요 없음)로 제공합니다.
핵심 약속: 모든 주장은 측정값에 의해 뒷받침되거나, 입증되지 않음으로 표시되거나, 미해결로 등록되어야 합니다. 지침이 필요하다면 기억할 문장: 아티팩트를 읽으면 누군가가 쓴 내용을 알 수 있지만, 실제 시스템만이 그것이 무엇을 의미하는지 알려줍니다.
워크플로
1. 먼저 증거 목록을 작성하세요
대화, 저장소, 로그 및 사용자로부터 데이터를 수집하기 전에 다음을 수집합니다:
- 연대기: 날짜, 시도한 내용, 실패한 내용, 놀라웠던 내용
- 정확한 숫자와 획득 방법을 포함한 모든 측정값
- 검증 실행: 무엇과 무엇을 비교했는지, 오류 수치
- 작업을 반복하는 데 필요한 도구, 파일 경로 및 명령어
- 미해결 질문 및 순수 가설
측정값, 날짜 또는 숫자를 지어내지 마십시오. 숫자가 누락된 경우 질문하거나 OPEN으로 표시하십시오. 조작된 데이터가 포함된 문서는 문서가 없는 것보다 나쁩니다. 기록의 공백은 기록의 일부입니다.
2. 규칙을 숙지하세요
작성하기 전에 references/style-guide.md를 읽으십시오. 스타일은 세부 사항에 있습니다(요점을 증명하는 캡션, 실패를 서사에 포함시킬 것, 정확한 숫자, 마케팅 금지). 콘텐츠 모듈을 작성할 준비가 되면 references/content-format.md를 읽으십시오.
3. 뼈대를 선택하세요
6개의 핵심 섹션을 번호 순서대로 포함합니다. 명시된 이유 없이 하나를 생략하지 마십시오. '실제 제품 구축'이라는 흐름이 있는 경우 스펙과 도구 사이에 사례 연구 섹션을 삽입할 수 있습니다.
| # | 섹션 | 필수 포함 사항 |
|---|---|---|
| 1 | 스토리 | 일별 타임라인; 모든 단계는 측정값에 기반; 막다른 골목과 놀라움 포함 |
| 2 | 방법 | 하나의 인식론 문장 + 테스트 아티팩트 → 질문 → 답변 표 |
| 3+ | 스펙 | 재구현이 가능할 정도로 정밀한 바이트/프로토콜/형식 표(신뢰도 태그 포함); 수학은 코드 블록으로 |
| −2 | 도구 & 방법 | 그대로 복사하여 작동하는 실제 명령어와 경로 |
| −1 | 검증 기록 | 정량적 오류를 포함한 모든 측정 실행 + 결론 콜아웃 |
| −0 | 미해결 질문 | 정직한 미지의 내용, 각각 OPEN 또는 HYP 태그 |
4. 작성 및 빌드
DOC를 정의하는 Python 모듈로 콘텐츠를 작성하고(references/content-format.md 형식 참조) 프로젝트 내에 보관하여 문서를 다시 생성할 수 있도록 한 후:
python3 <skill-dir>/scripts/build_doc.py content.py out.html
출력 파일을 열어 렌더링이 제대로 되는지 확인한 후 사용자에게 보여주십시오.
5. 자체 감사
- 모든 사실적 주장에는 태그가 붙거나 검증 기록에 포함되어 있습니다.
- 스토리에는 최소한 하나의 놀라움, 실패 또는 수정이 포함되어 있습니다. 작업에 그러한 내용이 없다면 드라마를 만들지 말고 솔직하게 말하십시오.
- 숫자는 정확하고 단위를 포함합니다(0.445초, '빠름'이 아님; 64,779픽셀, '많음'이 아님).
- 모든 그림 캡션은 이미지가 무엇을 증명하는지 설명하고, 무엇을 보여주는지가 아닙니다.
- 방법 명령어는 실제로 실행되었거나, 테스트되지 않음으로 명확히 표시되어야 합니다.
- 미해결 질문이 있습니다(항상 미해결 질문이 있습니다).
- 결론은 누군가가 기억할 수 있는 한 문장입니다.
태그
네 가지 신뢰도 태그는 해당 주장의 끝에 인라인으로 배치됩니다:
- HW(녹색) — 실제 테스트 대상 시스템에서 측정됨. 비장치 작업의 경우에도 적용됨: 라이브 실행, 벤치, 프로덕션에서 측정됨.
- FILE(파란색) — 조사된 모든 아티팩트(파일, 캡처, 로그)에서 참.
- HYP(보라색) — 모든 증거와 일치하지만 입증되지 않음.
- OPEN(회색) — 알 수 없음; 어느 쪽이든 증거 없음.
사실에는 태그가 붙습니다. 해설에는 붙지 않습니다. 도메인에 더 나은 이름이 있다면 문서 상단에서 한 번 이름을 바꾸고 일관되게 사용하십시오. 단, 이 네 가지 수준의 구분은 정확히 유지해야 합니다.
어조
동료 엔지니어, 1인칭 복수, 마케팅 제로. 숫자는 단위와 함께 정확하게. 문장은 짧게. 유머는 건조하고 드물게. 실패와 수정은 각주가 아닌 스토리에 포함됩니다. 동료는 역할로 표시합니다("한 동료가 두 개의 PNG 시퀀스를 전달했습니다…").
기원
TriCaster DVE 연구 로그(waldobjekt.org, 2026년 11월 1~3일, Claude와 함께 작성)에서 추출됨 — 원본 문서는 자체 build_doc.py를 제공합니다; 이 스킬은 그 설정을 일반화합니다.