| 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 결정 및 파일 경로 구성
- 인자로 slug가 주어지면 그대로 사용한다.
- 주어지지 않으면 대화 주제에서 자동 생성한다:
- 대화의 핵심 주제를 2~4 단어로 요약.
- kebab-case, 영문 권장 (필요 시 로마자 음차).
- 너무 일반적인 단어(
note, temp, save)는 피하고 주제를 식별 가능한 단어로 구성한다.
- 예: "인증 리팩토링 결정 논의" →
auth-refactor-decision
- 예: "
context-save 스킬 초안 설계" → context-save-skill-draft
- 자동 생성된 slug를 사용자에게 알린 뒤 진행한다 (별도 확인 요청 없음).
- 오늘 날짜(
YYYY-MM-DD)와 slug로 파일 경로를 구성한다: .ai/99_workspace/notes/<날짜>-<slug>.md.
- 동일 파일이 이미 있으면 숫자 접미사(
-2, -3)를 붙여 충돌을 피한다.
.ai/99_workspace/notes/ 디렉토리가 없으면 생성한다.
2단계: 관련 이슈 자동 감지
.ai/90_issues/active/ 하위에 issue-<번호>/ 디렉토리가 있는지 확인한다.- 있으면 해당 번호를 후보로 제시하고 연결 여부를 확인한다 (기본 Y).
- 여러 활성 이슈가 있거나 활성 이슈가 없으면 사용자에게 직접 지정/생략을 받는다.
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 등 공통 포맷.
- 파일 하나가 자기 완결적이므로 도구를 바꿔도 그대로 읽힌다.
- 도구별 세션 로그나 히스토리 파일에 의존하지 않는다.
