머신 간 동기화 검증 체크리스트
Claude Code 어댑터가 완전한 이식성 검사와 함께 새 호스트에서 올바르게 설치, 검증, 제거되는지 확인하는 검증 절차입니다.
범위. 이 체크리스트는 새 두 번째 호스트에서 Claude Code 어댑터의 설치 / 제거 이식성 레이어를 검증합니다. 다른 하니스는
site/content/docs/harnesses/<harness>.mdx아래에 문서화된 자체 호스트별 검증 레시피를 가집니다.
두 경로, 두 역할. 이 체크리스트를 읽는 동안 둘을 구분해 두십시오.
$HOME/.apothem은 엔진 홈입니다. 소스 트리를 클론하고 설치 프로그램이 읽어 들이는 위치이며,APOTHEM_HOME으로 재정의할 수 있습니다.~/.claude/는 Claude Code 구성 루트입니다. 어댑터의 출력 표면이며, 머티리얼라이즈된settings.json과 지원 하위 트리가 놓이는 곳입니다. 엔진은 결코~/.claude/에 설치되지 않습니다. 다른 하니스를 검증할 때는 어댑터 고유의 출력 경로로 대체하십시오.
새 두 번째 호스트에서 설치 / 제거 이식성 레이어에 대한 운영자 주도 검증. 게시 계층(
vX.Y.Z)은 단일 Windows 호스트에서 작성되었습니다. 이식성 주장(CLAUDE.mdportability: universal)은 다중 호스트 불변식이 의미를 갖기 전에 두 번째 호스트에서 엔드 투 엔드로 실행되어야 합니다. 이 체크리스트가 표준 두 번째 호스트 검증 레시피(Claude Code 어댑터)입니다.
1. 두 번째 호스트의 사전 조건
검증을 시작하기 전에 두 번째 호스트에서 다음을 실행하십시오:
| 항목 | 명령 | 예상 |
|---|---|---|
| Git 설치됨 | git --version | Git 2.40+ |
| Python 3.10+ 사용 가능 | python3 --version(POSIX) 또는 py -3 --version(Windows) | 3.10 / 3.11 / 3.12 / 3.13 |
| GitHub 인증(선택, 인증된 클론 / API 검사용) | gh auth status | 인증된 워크플로를 사용할 때 리포지토리의 승인된 계정으로 로그인됨 |
| 셸 사용 가능 | bash --version(POSIX) 또는 pwsh --version(Windows) | Bash 4+ 또는 PowerShell 7+ |
| 기존 엔진 홈 없음 | ls "$HOME/.apothem" 2>&1 | "No such file or directory" — 존재하면 진행 전에 백업 |
2. 클론 및 설치 검증
두 번째 호스트에서 다음을 실행하십시오:
# Clone the published repo to the engine home. This is NOT ~/.claude — that
# is the Claude Code configuration root the adapter writes into, and cloning
# a source tree on top of it would bury the harness's own config.
git clone https://github.com/ahmed-g-gad/apothem.git "$HOME/.apothem"
cd "$HOME/.apothem"
# (POSIX path) Run scripts/installer/install.sh dry-run first
bash scripts/installer/install.sh --dry-run # exit 0; prints Dry-run complete — no changes were made.
# (POSIX path) Run scripts/installer/install.sh for real
bash scripts/installer/install.sh # exit 0; idempotent
# (Windows path) PowerShell parallel
pwsh -File scripts/installer/install.ps1 -DryRun # exit 0; prints Dry-run complete - no changes were made.
pwsh -File scripts/installer/install.ps1 # exit 0각 명령의 종료 코드와 stdout 배너를 캡처하십시오. <second-host>/.audit/cross-machine-clone-install.md에 기록하십시오.
3. 4요소 규율 (src/apothem/rules/production-ready-prs.md 기준)
두 번째 호스트에서 네 가지 불변식을 각각 검증하십시오:
3.1 기존 대상 안전성
# Re-run installer at the same destination.
bash scripts/installer/install.sh # POSIX
pwsh -File scripts/installer/install.ps1 # Windows예상: 설치 프로그램이 기존 엔진 홈을 감지하고, 다시 설치하거나 중복하는 대신 그 안에서 릴리스 태그를 체크아웃합니다. 종료 코드 0.
3.2 사전 조건 검사됨
# Run from a copy outside any checkout, with git not on PATH.
d="$(mktemp -d)" && cp scripts/installer/install.sh "$d/" && PATH=<directory holding python3, click, rich and coreutils, but no git> /bin/sh "$d/install.sh" # POSIX (no git)예상: 설치 프로그램이 실행을 거부하고 명시적인 "git not found" 진단을 출력합니다. 종료 코드는 0이 아닙니다.
3.3 멱등한 재실행
# Run installer N times back-to-back.
for i in 1 2 3 4 5; do bash scripts/installer/install.sh; done # POSIX
1..5 | ForEach-Object { pwsh -File scripts/installer/install.ps1 } # Windows예상: 모든 호출이 종료 코드 0으로 끝납니다. 첫 번째 호출 이후 부작용이 없고, 중복 파일이 없으며, 셸 프로필 RC 중복도 없습니다.
3.4 환경 변수로 구성 가능
# Install to a non-default engine home. APOTHEM_HOME is the destination
# override the installers actually read; see the installer-environment-variables
# reference for the full set.
APOTHEM_HOME=/tmp/alt-apothem bash scripts/installer/install.sh # POSIX
$env:APOTHEM_HOME='C:\tmp\alt-apothem'; pwsh -File scripts/installer/install.ps1 # Windows예상: 설치 프로그램이 환경 변수를 존중합니다. 기본 $HOME/.apothem은 생성되지 않으며, 대체 대상에는 예상 레이아웃이 들어 있습니다.
4. 검증기 스위트 검증 (설치 후)
cd "$HOME/.apothem"
make validate # conformity gate --all --strict; exit 0
make headers-doctor # file-header-grep → passed:true
make ai-surfaces-doctor # multi-surface-coherence → passed:true
make plans-doctor # no-global-plans + plans-discipline-language
make lint # ruff check + ruff format --check + mypy
make test # exit 0, no failures예상: 모든 게이트가 녹색이어야 합니다. 종료 코드와 요약 줄을 캡처하십시오.
5. 제거 검증
# POSIX path — interactive uninstall
bash scripts/installer/uninstall.sh # answers: "y" to confirm
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code # reports the harness as not installed
# Re-install from the kept checkout, then uninstall non-interactively
bash scripts/installer/install.sh
bash scripts/installer/uninstall.sh --yes
PYTHONPATH="$HOME/.apothem/src/apothem/_vendor:$HOME/.apothem/src" python3 -m apothem verify --harness claude-code # reports the harness as not installed예상: 대화형 흐름은 프롬프트를 표시합니다. --yes는 일괄 실행에서 프롬프트를 건너뜁니다. 두 흐름 모두 실행 후 Claude Code 구성 루트에 Apothem이 머티리얼라이즈한 파일이 남지 않으며, apothem 심(shim)이 제거됩니다(~/.local/bin/apothem; %LOCALAPPDATA%\Microsoft\WindowsApps의 apothem.cmd 심은 uninstall.ps1로만 제거됩니다).
6. 안전 가드 검증
제거 프로그램의 가드는 센티널 파일 검사가 아니라 소스 트리 형태 검사입니다. 대상에 src/apothem/이 있고 pyproject.toml 또는 .claude-plugin/ 중 하나가 함께 있을 때만 진행합니다. 이 점검들은 스크립트가 읽는 변수인 APOTHEM_HOME으로 실행하십시오. 스크립트가 무시하는 변수로 작성한 점검은 가드를 검증하지 못하며, 실제 설치에 대해 제거 프로그램을 실행하게 됩니다.
# Run uninstall against a directory that is not an apothem source tree.
mkdir -p /tmp/not-an-apothem-install
APOTHEM_HOME=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes예상: 제거 프로그램이 거부하고 No apothem source found at /tmp/not-an-apothem-install — nothing to uninstall 메시지를 출력합니다. 종료 코드는 0이 아닙니다. 해당 경로는 건드려지지 않았습니다.
# Run uninstall against $HOME and /.
APOTHEM_HOME=$HOME bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3
APOTHEM_HOME=/ bash scripts/installer/uninstall.sh --yes 2>&1 | tail -3예상: APOTHEM_HOME=$HOME과 APOTHEM_HOME=/는 각각 No apothem source found at … 진단으로 거부되며, 어느 쪽도 파일 시스템을 건드리지 않습니다. 빈 APOTHEM_HOME은 의도적으로 제외합니다. 그 경우 ~/.apothem으로 대체되는데, 그곳에 실제 설치가 있을 수 있기 때문입니다.
# An explicit APOTHEM_SOURCE that is not a source tree is rejected separately.
APOTHEM_SOURCE=/tmp/not-an-apothem-install bash scripts/installer/uninstall.sh --yes예상: APOTHEM_SOURCE is not an apothem source tree: /tmp/not-an-apothem-install 메시지로 거부되며, 종료 코드는 0이 아닙니다.
7. 보고
두 번째 호스트 실행 후 결과를 다음 위치에 캡처하십시오:
<second-host>/.audit/cross-machine-clone-install.md(클론 + 설치 명령 결과)<second-host>/.audit/cross-machine-validators.md(4절 검증기 결과)<second-host>/.audit/cross-machine-uninstall.md(5~6절 제거 및 안전 결과)
발견 사항을 유지 관리자에게 전달하십시오:
- ✅ 4요소 규율 불변식이 모두 성립하고, 모든 검증기 게이트가 녹색이며, 모든 제거 안전 가드가 안전하지 않은 대상을 거부 → 게시 계층의
portability: universal주장이 엔드 투 엔드로 검증됨 - ❌ 실패가 있으면 → 실패한 절과 캡처된 출력을 담아
https://github.com/ahmed-g-gad/apothem/issues/new에 이슈를 등록하십시오. 유지 관리자가 분류합니다
8. 수용 기준
- §1 사전 조건 충족
- §2 POSIX 및 Windows 셸 모두에서 클론 및 설치 성공
- §3 4요소 규율 성립(기존 대상 안전성; 사전 조건 검사됨; 멱등; 환경 변수로 구성 가능)
- §4 모든 검증기 게이트 녹색
- §5 대화형 제거 성공;
--yes가 프롬프트 없이 성공 - §6 모든 안전 가드 거부 발동
- §7 결과가 문서화된 감사 경로에 캡처됨
새 두 번째 호스트에서 위의 모든 체크박스가 체크되면, 머신 간 동기화 검증이 완료되고 portability: universal 주장이 엔드 투 엔드로 검증된 것입니다.