# 유지보수

수정 전에 관련 지침, 현재 브랜치, 커밋하지 않은 변경을 확인합니다. 실제 동작은 코드에서, 의도한 동작은 명세에서 확인하고 무관한 변경은 보존합니다. 기능 설명의 기준 원문은 영어이며 한국어도 같은 변경에서 갱신합니다.

## 문서의 목적 보존하기

SKILL.md 진입점은 사용 조건 중심으로 짧게 유지합니다. 사람용 안내는 독자가 이해하고 실행할 수 있는 설명을 유지합니다. 스킬이나 bootstrap 파일 수를 줄인다는 이유로 README의 브랜드, 언어 선택, 초보자 사용법, 실행 예시, 복구 안내를 없애지 않습니다.

문서를 크게 다시 쓰기 전에는 이전 구조와 독자가 따라갈 경로를 비교합니다. 주요 항목은 유지하거나 현재 동작에 맞게 고치거나 명확한 링크로 옮깁니다. 종료된 기능은 상태를 밝혀 설명하세요. 과거 명령을 현재 명령처럼 남기거나 복구 안내까지 지우지 않습니다.

영문과 한국어는 명령, 한도, 동작, 검증 주장이 같아야 합니다. 소개 문구, 설명 순서, 언어 선택, 강조점은 의도적으로 다를 수 있습니다. 한국어는 대응 파일이 있다는 사실뿐 아니라 내용을 이해할 수 있는지도 검토합니다.

복사형 지침은 Markdown 링크뿐 아니라 규칙 자체도 검토합니다. 코드 글꼴로 적힌 파일명, 읽기 순서, 종료된 명령과 아키텍처 전제는 링크 검사가 통과해도 잘못될 수 있습니다. 제거할 규칙과 대체 내용을 대조하고 유용한 계약은 찾을 수 있는 참고 자료로 보존합니다. 개인 템플릿에는 목적에 필요한 설명을 남기며 스킬의 간결함을 길이 제한으로 적용하지 않습니다.

## 콘텐츠 배치

설치형 SKILL.md는 `skills/<category>/<name>`에 둡니다. 머리말에는 `name`과 `Use when`으로 시작하는 사용 조건 중심 `description`만 넣습니다. 긴 세부 내용은 해당 스킬의 참고 자료에 둡니다. 루트 참고 자료 모음은 선택 사항이며 시작할 때 전부 읽는 목록이 아닙니다.

프로젝트에 복사할 정책은 `templates/agents`, 기록은 `templates/project-playbook`에 둡니다. 복사형 지침에서 삭제된 템플릿이나 종료된 스킬 이름을 요구하지 마세요. 설치 스킬은 의도한 저장소에서만 동기화합니다. [콘텐츠 분류](classification.ko.md)를 참고하세요.

## 변경 단위별 검증

실질적인 통합 변경 후에는 저장소 검사를 실행합니다.

```powershell
npm run check
npm run typecheck
npm test
npm run validate:python
npm run validate:all
.\scripts\validate-skills.ps1
.\scripts\validate-translations.ps1
.\scripts\sync-skills.ps1 -WhatIf
.\install.ps1 -SkipValidation -WhatIf
.\update.ps1 -SkipValidation -WhatIf
```

문단 하나를 고칠 때마다 전체 테스트를 반복하지 않습니다. 이후 문서만 바뀌면 관련 검사를 하고, 동작 변경·실패·미해결 의문이 생기면 행동 검증을 다시 합니다. 실제 동기화에는 프로필을 지정하고 구버전 이전은 별도로 미리 봅니다.

사람용 문서는 격리된 폴더에서 초보자 순서를 따라 하고, 바뀐 명령 예시를 실행하며, 영문·한국어의 고정 문자열과 의미를 대조합니다. 링크와 표현도 확인합니다. 번역 대응과 링크 검사를 통과했다는 사실만으로 이해하기 쉽거나 의도를 보존했다고 판단하지 않습니다.

## 패키지와 공개 자료

Node ESM, `ai-agent-playbook` 패키지와 기본 명령, 호환용 축약 명령 `aapb`를 유지합니다. 두 명령은 같은 구현을 사용합니다. 소유권, 경로 제한, 이전, 복구 같은 실제 동작 경계를 의미 있게 검증합니다. Python 사전 릴리스 표기는 npm의 `next.N`을 PEP 440의 `devN`으로 대응합니다.

소스 폴더만 보지 말고 실제 npm 압축 파일을 확인합니다. 연결된 안내, 예시, README 이미지를 포함하세요. Markdown 링크와 HTML의 `src`·`href`, 언어별 상대 경로를 검사합니다. 코드 글꼴로 적은 경로와 명령은 따로 확인해야 합니다. 링크 검사는 문장 안의 존재하지 않는 경로를 잡지 못합니다.

스킬 소유권과 업데이트 검사는 파일 바이트를 정확히 비교합니다. Windows 체크아웃만으로 같은 설치본이 오래된 것으로 판정되지 않도록 Markdown·JSON 참조는 `.gitattributes`에 지정한 LF를 유지합니다. 체크아웃 회귀 검증은 `core.autocrlf`의 두 값을 시험합니다. 불일치를 숨기려고 설치된 사용자 파일의 줄바꿈을 바꾸거나 소유권 해시 검사를 완화하지 않습니다.

개인 경로, 인증 정보, 원시 로그, 로컬 프로젝트 기록, 백업, 시험 설치본은 공개 자료에서 제외합니다. 문제를 숨기려고 공개 문서나 번역 검사를 느슨하게 바꾸지 않습니다. 버전별 근거를 보관하고 과거 검사와 현재 압축 파일의 검사를 구분합니다.

## Git과 배포 기록

한국어 또는 사용자의 작업 언어로 Conventional Commit type/scope를 사용합니다. 실질적인 변경에는 간단한 본문과 실제 검증을 적습니다. 관련 경로만 스테이징하고 내용을 검토하며 훅을 지킵니다. 작업 이정표는 프로젝트에서 정한 로컬 기록에 남깁니다.

커밋, push, PR, 병합, npm 게시, 로컬 설치는 서로 다른 작업입니다. 사용자가 허용한 범위를 따르고 완료한 것만 보고하세요. [배포 점검표](publishing-checklist.ko.md)를 참고합니다.