# 런타임 구조

AAPB는 프로젝트 기록과 명시적으로 요청한 보조 작업을 다루는 로컬 Node.js ESM 프로그램입니다. 기본 CLI는 `ai-agent-playbook`이고 `aapb`는 축약 명령입니다. 선택형 MCP는 같은 기록 조회 기능 일부를 제공합니다. 구현과 실행은 에이전트 앱과 프로젝트의 기존 도구가 맡습니다.

## 요청이 결과로 나오는 흐름

```text
CLI 명령 / 프로젝트에 연결된 MCP 요청
  -> 명시적 작업 공간 등록 또는 지정 폴더의 플레이북 확인
  -> 기록 출처 또는 AST·Forge의 코드 저장소 하나 선택
  -> 경로·파일 형식·크기 확인
  -> 기록을 읽거나 명시적 작업 계획 생성
  -> 내용·경고·검사 범위·이어 읽기 정보 반환
```

CLI와 MCP는 같은 기록 조회 구현을 사용합니다. 설치, MCP, 문서 점검, Forge 모듈은 해당 명령을 선택할 때 불러옵니다. 자체 실행기, 예약기, 코드 색인 데이터베이스, 모든 작업에 강제되는 사전 검사 프로세스는 시작하지 않습니다.

## 기능별 책임

| 기능 | 맡는 일 | 이 결과만으로 알 수 없는 것 |
| --- | --- | --- |
| 기록 조회 | 목록, 문자열 검색·읽기, 문서 검증 | 프로젝트 코드의 정상 동작, 문장이 현재도 사실인지 |
| Bootstrap·구조 이전 | 최소·표준 기록, 선택형 AGENTS 링크, 제외 규칙과 관리 정보 | 기존 루트 규칙 교체, 과거 문서 재작성 |
| 작업 공간 등록 | 명시적 구성원, 공통 기록과 선택한 코드 대상 | 모든 하위 폴더의 자동 등록, 일괄 원격 쓰기 |
| 기록 작성 | 고유한 월별 일지와 주제 지식 템플릿 | 대화 이력 수집, 검증 사실 추론 |
| 스킬 관리 | 선택한 관리 설치본과 복구 | 모든 앱 플러그인, 연결 계정, 다른 스킬의 상태 |
| 문서·UI 점검 | 선택한 텍스트의 참고용 신호 | 실제 화면 검증, 작성 주체 판별 |
| Forge | 검토한 협업 계획과 명시적 원격 적용 | 작업 실행, 예약, 커밋, push |

## 데이터 규격

새 기록 응답은 `schemaVersion: 2`를 사용합니다. 유지한 문서 점검과 Forge 모듈은 기존 결과 규격을 유지합니다. 모든 결과의 필드가 같다고 가정하지 말고 종류와 해당 규격을 확인하세요.

기록 결과는 `ok`, 경고, 검사하지 못한 범위, 원본 위치, 이어 읽기 정보를 구분합니다. 상태와 검증의 `runtimeVerified`는 false입니다. CLI는 오류 때 0이 아닌 종료 코드를, MCP는 크기가 제한된 도구 결과를 반환합니다. [명령어 가이드](commands.ko.md)와 [응답 크기](record-responses.ko.md)에 세부 내용이 있습니다.

파일은 Markdown·JSON과 지원하는 텍스트 형식으로 유지하며 별도 기록 데이터베이스를 만들지 않습니다. 읽기 작업은 캐시나 보고서를 생성하지 않습니다. 기존 구조와 소유권 표식도 읽되, 여러 기록 폴더가 충돌하거나 내용을 읽지 못하면 이를 표시합니다.

## 쓰기·소유권·복구

설치는 실제 경로, 소유권, 해시를 확인하고 준비된 교체본을 적용합니다. 기존 내용은 같은 파일시스템의 백업으로 옮기고 복구 일지를 남깁니다. 되돌릴 때는 그 이후 편집을 확인합니다. 익숙한 이름이라는 이유만으로 관리 파일로 보지 않습니다.

부트스트랩은 기존 문서를 보존하면서 선택한 안내, 기록 링크나 관리 제외 변경을 적용할 수 있습니다. 별도의 복구 기록을 보관하세요. 작업 공간 등록 변경은 이전 등록 정보의 백업을 반환하며 기록 생성은 배타적 쓰기를 사용합니다.

기록 구조 이전은 이전 manifest와 표식을 저장한 뒤 호환되는 관리 정보만 바꾸고 사용자 문서를 보존합니다. 과거 근거에서 현재 사실을 자동으로 고르지 않습니다. 스킬 복구와 기록 복구의 차이는 [설치 안내](lifecycle.ko.md)에 있습니다.

Forge 미리보기는 인증된 통신 연결을 만들지 않습니다. 명시적 적용 시 제공 서비스와 인증 정보를 확인하고, 지원하는 작업인지와 원격 동시 변경 여부를 검사합니다. 일부 실패를 보고하되 로컬 프로젝트 작업을 자동으로 되돌리지 않습니다.

## 검증 결과를 구분하기

설정 파일은 의도를, 불러온 도구 목록은 사용 가능 여부를, 성공한 호출은 실제로 실행한 동작을 보여줍니다. 이들을 따로 기록하세요. 단위 테스트, SDK stdio 검사, 패키지 설치, 실제 앱 로딩도 서로 다른 검증입니다. [검증 보고서](verification.ko.md)는 확인한 범위를 기록하며 모든 앱과 플랫폼을 보장하지 않습니다.