tderoussel/session-log

세션 로그

작업 세션의 내구성 있는 기록을 작성합니다. 이 로그는 이후에 읽는 모든 사람(지금으로부터 6주 후, 이 컨텍스트가 전혀 없는 당신을 포함하여)에게 신뢰할 수 있는 진실로 취급됩니다. 정확성이 꾸밈보다 중요합니다.

실행 시점

• 빌드, 수정, 감사 또는 연구 작업이 방금 끝났을 때
• 세션이 종료되고 다음 세션에 필요한 상태가 있을 때
• 근본 원인이 파악되었고 그 메커니즘을 기록할 가치가 있을 때

사소한 작업에는 실행하지 마세요. 단 한 줄의 수정에는 로그가 필요하지 않습니다.

저장 위치

프로젝트가 세션 기록을 보관하는 곳(예: docs/sessions/ 디렉토리, 노트 보관소, 위키)에 저장합니다. 명확하지 않으면 한 번 묻고, 그 후에는 일관성을 유지하세요.

날짜와 간단한 설명이 포함된 파일 이름은 정렬 및 검색에 용이합니다: YYYY-MM-DD 간단한 설명.md.

단계

1. 작성 전 사실 수집

대화만의 기억으로 작성하지 마세요. 다음을 수집하세요:

• PR 번호, 커밋 SHA, 마이그레이션 타임스탬프, 배포 ID
• 실제로 확인된 내용 및 확인에 사용된 명령어
• 실패한 내용 및 아직 해결되지 않은 내용
• 인간만이 할 수 있는 모든 것

사실이 확인될 수 없으면, 생략하거나 단언하지 말고 '확인되지 않음'으로 표시하세요.

2. 본문 작성

# YYYY-MM-DD — <근본 원인이 파악되거나 출시된 내용>

<작업이 어떻게 진행되었는지를 명명하는 한 줄: 누가 계획하고, 누가 빌드하고, 누가 리뷰했는지.>

## 발생한 내용

- 메커니즘을 먼저. 무엇이 아니라 왜 발생했는지.
- 구체적인 증거: PR 번호, SHA, 타임스탬프, 행 수, 로그 줄.
- 입증된 것과 추론된 것을 명시적으로 구분하세요.

## 수정

1. 번호가 매겨진 단계. 각 단계는 무엇이 어떻게 확인되었는지를 명시합니다.

## 절대 위반 금지 규칙
<세션이 금지 사항을 생성한 경우에만 해당. 각각을 발생시킨 인시던트에 근거를 두세요.>

## 남은 항목 — 인간 필요

- [ ] 인간만이 할 수 있는 일

링크: <관련 문서>

노트 시스템이 프론트매터를 사용하는 경우, outcome 필드를 포함하세요: 이전에는 사실이 아니었지만 지금은 사실인 것을 명시하는 하나의 완전한 문장. 파일에서 가장 많이 읽히는 줄입니다. 레이블이 아닌 실제 주장으로 작성하세요.

3. 모두가 놓치는 두 섹션

## 남은 항목과 링크 푸터는 필수입니다. 이 두 섹션은 가치를 전달하는 부분이며 가장 자주 생략됩니다 — 한 보관소에서 230개의 기존 로그를 측정한 결과, 각각 약 21%와 28%의 로그에만 나타났습니다.

매번 둘 다 작성하세요. 인간을 위해 실제로 보류된 항목이 없으면, 제목을 삭제하지 말고 없음 — 보류된 항목 없음.이라고 작성하세요.

4. 모든 주장 표시

각 주장에 인라인으로 확인됨 (방법) 또는 추정됨 (확인하지 않은 이유) 레이블을 지정하세요. 모호하게 하지 마세요.

"확인됨"은 인간이나 명령어가 실제로 확인했음을 의미해야 합니다. 프로덕션에 대한 주장은 프로덕션에 대한 쿼리를 필요로 합니다 — 통과한 테스트, 병합된 PR, 녹색 배포가 아닙니다.

5. 저장 전 모든 링크 확인

작성하기 전에 각 링크 대상을 실제 파일과 확인하세요. 노트 시스템은 깨진 참조를 빠르게 축적하며, 죽은 링크로 가득한 로그는 아무도 신뢰하지 않습니다.

6. 프로젝트 상태 업데이트

작업이 프로젝트 상태를 변경한 경우, 해당 프로젝트의 메인 문서에 날짜가 있는 상태 섹션을 추가하세요 — 가장 최신이 위로, 앞에 추가하며, 기록을 덮어쓰지 마세요.

작업이 인계 문서와 함께 프로그램을 진행한 경우, 다음 세션이 올바르게 이어받을 수 있도록 해당 문서를 제자리에서 업데이트하세요.

7. 학습 내용 피드백

사용자가 세션 중에 무언가를 수정했다면, 그 교훈을 내구성 있는 곳(규칙 파일, 메모리 저장소, 이 스킬 자체)에 기록하세요. 이것이 수정 사항이 반복되지 않도록 하는 방법입니다.

하우스 스타일

• 구체적이고 반증 가능해야 합니다. 모호한 요약은 여기서 아예 없는 것보다 더 나쁩니다.
• 확인 방법을 언급하지 않고 상태를 주장하지 마세요.
• 나쁜 소식을 먼저 전하세요. 숨기지 마세요.
• 당신의 컨텍스트가 전혀 없는 독자를 위해 작성하세요.

하지 말아야 할 것

• 기존 로그를 덮어쓰지 마세요. 먼저 읽고, 그 다음 편집하세요.
• 머신 생성 디렉토리에 작성하지 마세요.
• 노트 옆에 스크래치 파일이나 빌드 출력물을 생성하지 마세요.