# 프로젝트 기록 구조

`CURRENT.md`에서 현재 목표, 제약, 확인한 상태, 다음 할 일을 찾을 수 있게 합니다. 자세한 내용은 필요할 때 링크로 연결합니다. 최소 구조의 목적은 같은 정보를 여러 문서에 반복해서 적지 않는 것입니다. 유용한 과거 기록까지 버리라는 뜻은 아닙니다.

## 새 프로젝트에 만드는 파일

`--records minimal`은 아래의 시작 문서와 메타데이터를 만듭니다. 새 대화형 기본값인 `standard`는 없는 작업 일지·지식 안내도 추가합니다. `--kind workspace`는 명시적 구성원 등록을 추가합니다.

```text
.ai-agent-playbook/
  CURRENT.md                        직접 편집할 현재 상태
  manifest.json                     기록 구조를 나타내는 관리 정보
  .ai-agent-playbook-install.json    소유권 확인에 쓰는 관리 정보
  worklogs/README.md                표준 작업 일지 안내
  knowledge/README.md               표준 지식 안내
  workspace.json                    작업 공간 등록 시에만 생성
```

Bootstrap은 소스 아키텍처나 빈 계약·작업 절차 트리를 만들지 않습니다. 루트 지침은 기본적으로 보존하며 `--agents link`를 선택하면 짧은 기록 링크를 추가하거나 작은 루트 지침 파일을 만들 수 있습니다. 새 소유권 표식에서 `CURRENT.md`는 사용자 편집 문서로 구분하므로 수정하는 것이 정상입니다. Manifest와 표식은 설치·이전 도구가 관리 대상을 확인하는 데 쓰며, 주변의 모든 파일을 관리 파일로 취급하지 않습니다.

## CURRENT.md에 적을 내용

| 항목 | 적으면 좋은 내용 | 예시 |
| --- | --- | --- |
| 목표 | 현재 결과물과 바로 다음 단계 | CSV 내보내기 추가. 다음은 날짜 열 형식 확인 |
| 제약 | 이번 작업에 영향을 주는 결정 | 기존 열 이름과 행 순서 유지 |
| 확인한 상태 | 근거와 확인 범위를 포함한 사실 | 내보내기 단위 테스트 통과. 브라우저 다운로드는 미검증 |
| 상세 기록 | 필요한 근거 문서 링크 | CSV 계약과 해당 테스트 보고서 |

다음 할 일은 목표에 함께 적거나 별도 항목으로 둘 수 있습니다. 제목도 프로젝트 언어에 맞춰 쓰세요. 정해진 제목 순서보다 실제 경로와 검증 근거가 중요합니다.

예를 들어 내보내기 결정을 자세히 설명해야 할 때만 `decisions/csv-export.md`를 만들고, CURRENT.md에 `[CSV 내보내기 결정](decisions/csv-export.md)`처럼 연결합니다. 이 경로는 설명용 예시이므로 실제 문서를 만든 뒤 링크하세요. 요구사항, 검토한 대안, 긴 테스트 결과는 상세 문서에 두고 모든 기록에 반복하지 않습니다.

## 상세 기록과 인수인계

현재 유효한 규칙과 계약은 `knowledge/`에 출처, 적용 저장소, 확인 날짜와 불확실성을 함께 남깁니다. 새 일지는 `worklogs/YYYY-MM/` 아래 고유한 날짜별 파일로 상세 근거를 보존합니다. 월과 주제는 처음 필요할 때 만듭니다. CURRENT.md에는 이력을 반복하지 않고 관련 기록을 연결합니다. `worklog new/list`, `knowledge new`, 필터와 초안 검토는 [오래 유지할 기록](durable-records.ko.md)에서 설명합니다.

명세, ADR(아키텍처 결정 기록), 계약, 계획, 검증 기록, 인수인계는 프로젝트에서 이미 쓰는 위치를 우선합니다. [spec-artifacts 스킬](skill-catalog.ko.md)은 형식을 제공하지만 전부 작성하도록 요구하지 않습니다.

인수인계에는 바뀐 내용, 확인한 근거, 아직 모르는 점, 다음 할 일을 남깁니다. 사실을 재확인하는 데 필요한 명령과 원본 링크는 정확히 보존하세요. 도구가 만든 보고서는 검토할 근거로 표시합니다. 과거 기록이 곧 현재 사실은 아니며, 설정 검사 성공이 실제 실행의 증거는 아닙니다.

## 기존 구조 읽기

등록된 구성원은 기본적으로 상위 작업 공간의 공통 기록을 사용합니다. `--record-source repo:<id>`로 구성원의 기존 로컬 기록을 이동 없이 선택할 수 있습니다. 미등록 하위 폴더는 연결되지 않습니다. [작업 공간](workspaces.ko.md)을 참고하세요. 아래 구버전 폴더의 모호성 판단은 선택한 기록 위치 안에서 적용됩니다.

기존 기록과의 호환을 위해 `.ai-agent-playbook/`, `.ai-playbook/`, `ai-playbook/`을 인식합니다. 이 폴더가 둘 이상 있으면 어느 기록이 기준인지 불명확하므로 임의로 선택하거나 합치지 않습니다.

기존 `START_HERE.md`, `memory/`, `maps/`, `contracts/`, `workflows/`, `runtime/` 기록이 있으면 계속 읽을 수 있습니다. 상태 조회는 CURRENT.md를 우선하고, 없으면 START_HERE.md를 시작 문서로 표시할 수 있습니다. 모든 작업에 예전의 전체 읽기 순서를 강제하지는 않습니다. 프로젝트 지침과 관련 링크를 따르세요.

읽기 경로는 선택한 플레이북 폴더 기준입니다. Markdown, 일반 텍스트, JSON/JSONL, YAML, TOML을 지원합니다. 연결된 경로, 바이너리, 큰 파일, 제외 디렉터리는 읽기를 제한하거나 건너뛰고 경고를 남깁니다. 자세한 범위는 [응답 크기 안내](record-responses.ko.md)에 있습니다.

## 검증과 이전

`ai-agent-playbook records validate "<project>" --json`은 문서 구조, 링크, 관리 파일 해시를 확인합니다. 구버전의 수정된 관리 문서는 유용한 사용자 기록일 수 있습니다. 검사 결과를 깨끗하게 만들려고 덮어쓰지 말고 내용을 검토하세요.

구조 이전은 관리 정보만 바꾸고 기존 문서와 근거 링크를 보존합니다. 읽을 수 있는 CURRENT.md와 수정되지 않은 관리 정보가 필요합니다. 도구는 문장이 최신 사실인지를 판정하지 못합니다. 미리보기·명시적 적용·보호된 복구 절차는 [설치 안내](lifecycle.ko.md)에 있습니다. 폴더 이동이나 과거 요약은 자동으로 하지 않습니다.