context-save

name	context-save
description	대화 중 중요한 맥락(배경, 결정, 미결 사항, 다음 액션)을 `.ai/99_workspace/notes/` 아래 마크다운 파일로 저장합니다. 맥락 저장, context save, 임시 저장, 논의 스냅샷, 작업 메모 시 사용합니다.

개요

현재 대화에서 오간 논의의 핵심을 AI 에이전트 독립적인 마크다운 파일로 .ai/99_workspace/notes/에 임시 저장하는 스킬입니다. 다음 세션의 에이전트(Claude Code, Codex, Antigravity, GitHub Copilot 등)가 파일만 읽고도 맥락을 이어갈 수 있도록 대화 재현이 아닌 상태 스냅샷을 기록합니다.

.ai/99_workspace/는 임시 작업공간이며, 주 사용 흐름은 다음과 같습니다:

저장 → 다음 세션에서 /issue-work --resume으로 자동 로드 → 흡수 후 사용자가 수동 정리.

영구 보존을 가정하지 않으며, 필요 시 정식 위치(50_adr/, 40_domain/, 90_issues/)로 사용자가 승격합니다.

언제 쓰는가

• 이슈 진행 중 특정 Task가 완전히 마무리되지 않았지만 맥락을 잠시 붙잡아두고 싶을 때.
• 이슈 등록 없이 자유롭게 논의한 내용을 다음 세션까지 이어가고 싶을 때.
• 결정은 났지만 다음 세션에 실행·검증이 남아 맥락을 넘기고 싶을 때.

관련 skill

• ai-workspace (권장): .ai/99_workspace/ 구조를 활용합니다. 없으면 필요한 디렉토리를 직접 생성합니다.
• issue-work (연동): 이슈 작업 중 실행하면 활성 이슈를 자동 감지하여 related-issue로 연결합니다. issue-work --resume은 이미 .ai/99_workspace/ 하위를 모두 읽으므로 저장된 노트는 별도 설정 없이 다음 세션에 복구됩니다.

참조 문서

• 공통 규칙: .ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다.
• 스킬 고유 추가 참조:
  • .ai/90_issues/active/ — 활성 이슈 번호 자동 감지 (있을 경우)
  • .ai/99_workspace/notes/ — 기존 노트 파일명 충돌 확인

---

핵심 원칙

상태 스냅샷, 대화 재현 금지

• 누가 뭐라고 말했는지가 아니라 결론과 근거만 기록한다.
• 특정 AI 도구의 UI 용어, 세션 ID, 내부 상태에 의존하지 않는다.
• 파일 하나만 읽어도 제3자가 상황을 파악할 수 있어야 한다.

자기 완결성

• 상대 시간 금지 → 항상 절대 날짜(YYYY-MM-DD).
• 파일 경로는 repo 루트 기준 상대 경로.
• 외부 참조는 URL, 이슈/PR 번호, 커밋 해시로 명시.

이슈와 느슨한 결합

• 이슈 진행 중이어도 맥락 노트는 이슈 파일과 독립적으로 저장한다.
• 연결은 프론트매터 related-issue 필드로만 한다.
• 노트는 임시 저장 성격이므로 이슈 종료 후 정리는 사용자가 수동으로 판단한다.

---

저장 위치 및 파일 규칙

.ai/99_workspace/notes/
└── YYYY-MM-DD-<slug>.md

• 파일명 형식: YYYY-MM-DD-<slug>.md
  • 예: 2026-04-24-auth-refactor-decision.md
• slug: 주제를 요약한 kebab-case 짧은 식별자. 영문 권장, 필요 시 한글 허용.
• 충돌 처리: 같은 날 같은 slug가 이미 있으면 -2, -3 숫자 접미사를 붙인다.

---

실행 흐름

slug는 기본적으로 대화 주제에서 자동 생성합니다. 인자로 직접 지정할 수도 있습니다.

기본 (자동 생성):

사용자: /context-save

스킬:  slug 자동 생성 → `auth-refactor-decision`
       활성 이슈 #42 가 감지되었습니다. related-issue로 연결할까요? (Y/n)
사용자: Y

스킬:  현재 대화에서 배경/결정/미결/다음 액션을 추출하여 작성합니다...
       → .ai/99_workspace/notes/2026-04-24-auth-refactor-decision.md

slug 직접 지정:

사용자: /context-save auth-refactor-decision

---

실행 절차

1단계: slug 결정 및 파일 경로 구성

1. 인자로 slug가 주어지면 그대로 사용한다.
2. 주어지지 않으면 대화 주제에서 자동 생성한다:
   • 대화의 핵심 주제를 2~4 단어로 요약.
   • kebab-case, 영문 권장 (필요 시 로마자 음차).
   • 너무 일반적인 단어(note, temp, save)는 피하고 주제를 식별 가능한 단어로 구성한다.
   • 예: "인증 리팩토링 결정 논의" → auth-refactor-decision
   • 예: "context-save 스킬 초안 설계" → context-save-skill-draft
3. 자동 생성된 slug를 사용자에게 알린 뒤 진행한다 (별도 확인 요청 없음).
4. 오늘 날짜(YYYY-MM-DD)와 slug로 파일 경로를 구성한다: .ai/99_workspace/notes/<날짜>-<slug>.md.
5. 동일 파일이 이미 있으면 숫자 접미사(-2, -3)를 붙여 충돌을 피한다.
6. .ai/99_workspace/notes/ 디렉토리가 없으면 생성한다.

2단계: 관련 이슈 자동 감지

1. .ai/90_issues/active/ 하위에 issue-<번호>/ 디렉토리가 있는지 확인한다.
2. 있으면 해당 번호를 후보로 제시하고 연결 여부를 확인한다 (기본 Y).
3. 여러 활성 이슈가 있거나 활성 이슈가 없으면 사용자에게 직접 지정/생략을 받는다.

3단계: 맥락 증류 및 문서 작성

현재 대화에서 다음을 추출하여 templates/context-note-template.md에 따라 작성한다.

섹션	내용
배경 (Why)	왜 이 논의가 시작되었는가. 문제 상황.
논의 요약	핵심 옵션, 트레이드오프, 근거. 대화 재현 금지.
결정사항	결론난 것. - [x] 체크박스로 표현.
미결 / 열린 질문	다음에 확인할 것. - [ ] 체크박스로 표현.
다음 액션	누가 무엇을. 없으면 "없음"이라고 명시.
참조	파일 경로, 커밋 해시, 이슈/PR URL 등.

4단계: 결과 보고

## context-save 실행 결과

- 파일: .ai/99_workspace/notes/2026-04-24-auth-refactor-decision.md
- 관련 이슈: #42 (또는 없음)
- 요약: 미결 2건, 다음 액션 1건
- 다음 세션에서 `/issue-work --resume`으로 자동 로드됩니다.

---

산출물 템플릿

templates/context-note-template.md가 단일 출처이며, 본문에 템플릿 내용을 중복 기재하지 않는다. 섹션 구성과 작성 지침은 3단계의 섹션 표와 템플릿 내 주석을 따른다.

---

라이프사이클

노트는 임시 저장이 원칙입니다. 자동 삭제·자동 승격은 없으며, 정리는 사용자가 수동으로 판단합니다.

단계	주체	동작
저장	/context-save	.ai/99_workspace/notes/에 노트 생성
로드	/issue-work --resume	.ai/99_workspace/ 전체를 읽어 다음 세션에 자동 복구
정리	사용자	흡수 완료 시 삭제 / 영속 가치가 있으면 정식 위치로 이동(승격)

정식 위치로 승격할 수 있는 대상:

내용 성격	승격 위치
기술적 설계 결정	.ai/50_adr/
도메인 정책·명세	.ai/40_domain/
새 이슈로 발전	.ai/90_issues/active/

.ai/99_workspace/는 임시 작업공간이므로 노트가 쌓여 있어도 프로젝트 구조상 허용됩니다.

---

다른 AI 도구와의 호환성

• 마크다운 + YAML 프론트매터는 Claude Code, Codex, Antigravity, GitHub Copilot 등 공통 포맷.
• 파일 하나가 자기 완결적이므로 도구를 바꿔도 그대로 읽힌다.
• 도구별 세션 로그나 히스토리 파일에 의존하지 않는다.