빠른 시작
Apothem을 설치하고, 프로필을 작성하고, 첫 하니스를 머티리얼라이즈한 다음 검증합니다 — 예상 출력이 함께 담긴 복사·붙여넣기 투어입니다.
이 페이지는 아무것도 없는 상태에서 검증된 하니스 구성까지 가는 빠른 경로입니다. 설치하고, 공유 프로필을 작성하고, 한 도구의 네이티브 구성을 머티리얼라이즈하고, 이를 확인한 다음, 첫 편집을 합니다. 모든 명령은 실제 명령이며 복사하여 붙여넣어 실행할 수 있고, 각 단계는 깨끗한 실행이 무엇을 출력하는지 보여 줍니다. 설치 자체는 2분 이내에 끝납니다. 프로필 편집만이 원하는 만큼 시간이 걸리는 유일한 부분입니다.
이 페이지를 마치면 직접 작성한 프로필에서 생성된, 동작하는 하니스 구성을 갖게 되며, 프로필 변경 사항을 한 도구 또는 모든 도구에 다시 내보내는 단 하나의 명령도 알게 됩니다.
설명이 곁들여진 느긋한 버전을 원하시나요?
시작하기 튜토리얼은 같은 과정을 다루면서 각 단계와 그 단계가 왜 중요한지를 더 자세히 설명합니다. 이 페이지는 간결하고 출력 중심인 투어입니다.
예시 하니스로 Claude Code를 사용합니다. 설치 프로그램의 기본값입니다. 어느 단계에서든 어댑터 이름을 바꾸면 다른 도구를 대상으로 할 수 있습니다. 지원되는 모든 이름은 하니스 목록에 있습니다.
1. Apothem 설치
Apothem은 자체 완결형 런타임으로 배포됩니다. 엔진은 벤더링된 종속성과 함께 소스 트리에서 바로 실행됩니다. 명령 하나로 소스를 가져오고, 엔진을 배치하고, 첫 하니스를 머티리얼라이즈합니다. 설치 프로그램은 먼저 서명된 릴리스를 검증하므로, 첫 설치 전에 메인테이너 서명 키를 한 번 가져오고 지문이 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163인지 확인하세요:
curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'그다음 설치 프로그램을 실행하세요:
curl -fsSL https://apothem.ahmedgad.com/install.sh | bashirm https://apothem.ahmedgad.com/install.ps1 | iex설치 프로그램에는 시스템 Python 3.10+가 필요하며, 네트워크 형식에는 git과 gpg도 필요합니다. 설치 프로그램은 사전 요건을 확인하고 엔진을 ~/.apothem 아래에 배치합니다. click 또는 rich가 없으면 사용자가 확인하거나 --yes(PowerShell에서는 -Yes) 또는 APOTHEM_AUTO_INSTALL_DEPS=1을 주었을 때 해당 패키지를 설치하며, 그렇지 않으면 실행할 pip 명령을 안내하며 중단합니다(사전 요건 한눈에 참조). 설치가 끝나면 다음 단계 안내 배너를 출력합니다. POSIX에서 심(shim)의 디렉터리가 이미 PATH에 있으면 배너는 다음과 같습니다:
Installation complete.
The 'apothem' command is on your PATH.
Recommended first step — the guided setup (profile -> preview -> install):
apothem quickstart프로필 없이 하는 첫 실행
아직 프로필이 없다면 설치 프로그램은 예시 프로필을
~/.config/apothem/profile.yaml에 복사하고 계속 진행합니다. 같은 실행에서 첫
하니스를 머티리얼라이즈하고 검증합니다. 예시의 신원 필드는 플레이스홀더이므로
설치 과정에서 안내 메시지가 출력됩니다. 2단계에서 프로필을 자신의 것으로 만든
다음, 5단계에서처럼 apothem update --harness <name>으로 적용하세요.
`apothem` 명령
설치 프로그램은 apothem 심을 $HOME/.local/bin(POSIX) 또는
%LOCALAPPDATA%\Microsoft\WindowsApps(Windows)에 쓰며, PATH는 절대 수정하지
않습니다. 그 디렉터리가 PATH에 있으면 엔진을 apothem <command>로 직접
실행합니다. 아직 PATH에 없다면 배너는 심이 필요 없는 자체 완결형 대체 명령인
PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>를 출력합니다.
배너가 출력한 정확한 접두사를 각 명령 앞에 붙이세요.
설치 가이드는 다른 설치 경로, 즉 Claude Code
플러그인(/plugin marketplace add ahmed-g-gad/apothem 다음
/plugin install apothem@apothem), VS Code 계열 및 기타 도구 네이티브 확장,
온디맨드 npx 형식(npx @ahmed-g-gad/apothem <command>)을 환경 변수 옵션과 함께
다룹니다.
2. 공유 프로필 만들기
apothem profile init은 스키마상 유효한 가장 작은 프로필을
~/.config/apothem/profile.yaml에 씁니다. 1단계에서 설치 프로그램이 예시를 복사한
경우처럼 이미 그 위치에 프로필이 있으면, init은 오류를 내며 중단하고 파일을
그대로 둡니다. 덮어쓰려면 --force를 전달하고, 아니면 파일을 그대로 두고 아래에
나온 대로 편집하세요. 프로젝트용 또는 CI 전용 프로필을 다른 곳에 둘 때는
--profile PATH를 전달하세요.
apothem profile init
apothem profile show --json스캐폴드는 가짜 플레이스홀더 신원 데이터를 사용하며, 하니스 출력을 설치하기 전에
안전하게 편집할 수 있습니다. show --json은 이를 다시 읽어 모든 기본값이 채워진
검증된 프로필을 schema_version부터 보고합니다. 명령은 이를 한 줄로 출력하며,
여기서는 펼쳐서 보여 줍니다.
{
"schema_version": 1,
"identity": {
"name": "Example User",
"role": "senior software engineer",
"email": "[email protected]",
"github": "example-user"
},
"preferences": {
"language": "python",
"style": "concise"
},
"rules": [],
"seriousness": "PERSONAL_USE",
"enforcement": {
"sprints": false,
"agent_teams": false,
"multitasking": false,
"continuous_execution": false,
"learning_loop": false
},
"mcp_servers": {},
"agent_mcp_servers": {},
"harnesses": {},
"exclude_harnesses": [],
"workspace": {
"directory_name": ".apothem",
"scope": "project-local"
}
}잘못된 편집이 드러나는 곳도 여기입니다. YAML이 유효하지 않으면, 하니스 구성이
쓰이기 전인 이 단계에서 show가 이를 보고합니다. apothem profile edit(편집기에서
엽니다)으로 프로필을 자신의 것으로 만들거나, 키 하나를 그 자리에서 설정하세요.
apothem profile set identity.name "Your Name"3. 하니스 어댑터 설치
주로 사용하는 하니스의 어댑터를 머티리얼라이즈합니다. 이 명령은 프로필을 읽고 그 도구의 네이티브 구성을 씁니다.
apothem install --harness claude-code✓ Installed claude-code -> /home/you/.claude/settings.json프로젝트 범위 어댑터는 규칙 파일을 프로젝트 안에 쓰므로 --project PATH가
필요합니다. 그중 일곱 개는 스킬과 공유 규칙도 홈 디렉터리의 폴더에 쓰며,
--project는 그 위치를 바꾸지 않습니다. --dry-run을 사용하면 파일을 쓰지 않고
어떤 설치든 미리 볼 수 있습니다.
apothem install --harness cursor --project . --dry-run
apothem install --harness cursor --project .--harness all을 사용하면 레지스트리 기반 세트 전체를 한 번에 설치합니다. 이
선택은 프로젝트 범위 파일과 사용자 범위 파일을 모두 쓰므로, 명령은 구체적인 대상을
위치별로 묶어 출력합니다. 대화형 터미널에서는 프로젝트 루트 바깥에 쓰기 전에
확인을 받습니다. 터미널이 없는 실행, --yes를 준 실행, --format json을 준
실행은 묻지 않고 씁니다. --dry-run은 아무것도 쓰지 않습니다. 전체 세트를
설치하려면 다음을 실행하세요.
apothem install --harness all --project .지원되는 모든 이름은 전체 하니스 목록에서, 전체 옵션 세트는 install 참조에서 확인하세요.
4. 검증
머티리얼라이즈는 작업의 절반일 뿐입니다. verify는 하니스의 예상 구성 파일이
제자리에 쓰였고 유효한지 확인합니다.
apothem verify --harness claude-code✓ claude-code is verified at /home/you/.claude/settings.jsonverify는 관리 대상이 없거나, 관리 파일이 비어 있거나, JSON 또는 YAML 구성이
파싱되지 않으면 0이 아닌 코드로 종료합니다. --profile PATH를 추가하면 설치된
파일이 그 프로필과 다를 때도 실패하므로, verify가 드리프트 검사 역할을 합니다. 이
옵션이 없으면 오래된 구성도 검증을 통과합니다. 0이 아닌 종료 코드 덕분에 verify는
설정 스크립트에서 게이트 역할을 할 수 있습니다. 등록된 모든 어댑터에 걸친 머신
전체 상태 점검은 다음을 실행하세요.
apothem doctordoctor는 설치된 모든 하니스를 점검합니다. 각 하니스는 검증을 통과해야 하며, 그
설치가 등록한 각 훅 명령이 시작되어야 합니다. 설치하지 않은 하니스는 목록에
표시되지만 실패가 아니므로, 어떤 점검도 실패하지 않으면 설치된 하니스가 하나뿐이어도
doctor는 0으로 종료합니다.
5. 첫 실행
방금 구성한 하니스(이 예에서는 Claude Code)를 열고 아무 프로젝트에서나 세션을 시작하세요. 2단계에서 설정한 프로필이 이제 그 도구 동작의 일부입니다. 이것이 동작하는 첫 실행입니다. 하나의 프로필이 실제 세션을 형성합니다.
나중에 프로필을 변경하면, 재설치하지 않고 다시 적용하세요.
apothem update --harness claude-code다른 어댑터 이름을 지정하면 그 도구에 프로필을 다시 적용합니다(프로젝트 범위
어댑터에는 --project PATH를 추가하세요). 지원되는 모든 하니스에 다시 적용하려면
--harness all --project .를 전달하세요.
다음 단계
- 하니스 더 추가하기 — 도구마다 3단계를 반복합니다.
- 첫 규칙 작성하기 — 모든 하니스가 상속하는 단위입니다.
- 플랜 작성하기 — 결정적 플랜 파이프라인을 통해 미션 전체를 진행합니다.
- CLI 참조 — 모든 명령, 플래그, 종료 코드입니다.