Cursor
Cursor(GA)용 Apothem 하니스 어댑터.
벤더: Anysphere
설치 이름: cursor
상태: GA
네이티브 구성: 프로젝트 루트의 .cursor/rules/
설치
apothem install --harness cursor --project /path/to/project어댑터는 공유 Apothem 규칙과 거버넌스 표면으로부터 프로젝트 범위의 .mdc 규칙
파일 하나를 렌더링하고, Apothem의 도우미를 프로젝트에 Cursor 서브에이전트로
작성하며(서브에이전트 참조), 프로젝트의 hooks.json에 훅 하나를
추가합니다(훅 참조).
또한 Apothem의 스킬과 그 스킬이 인용하는 규칙 및 템플릿을, 프로젝트를 건드리기 전에 사용자 홈에 작성합니다(프로젝트 외부의 파일 참조).
작성되는 파일:
<project>/.cursor/rules/apothem-rules.mdc: 규칙 파일.- 각 Apothem 도우미에 대한
<project>/.cursor/agents/<name>.md: 프로젝트 안. <project>/.cursor/hooks.json:sessionStart항목 하나가 추가됩니다. 그 안에 있는 여러분 자신의 항목과 키는 유지됩니다.<project>/.apothem/support/cursor/hooks/: 훅 스크립트, 프로젝트 안.- 각 Apothem 스킬과 커맨드에 대한
~/.agents/skills/<name>/SKILL.md: 사용자 홈 안. ~/.config/apothem/rules/및~/.config/apothem/templates/: 사용자 홈 안.
규칙 파일은 규율을 요약하고 그 폴더들을 명시하므로, 작업에 필요할 때 모델이 스킬이나 규칙 파일을 열 수 있습니다.
프로젝트 외부의 파일
설치는 프로젝트의 어떤 것도 변경하기 전에 Apothem의 스킬을 사용자 홈에도 작성합니다.
| 폴더 | Apothem이 그곳에 작성하는 것 |
|---|---|
~/.agents/skills/ | 각 Apothem 스킬마다 SKILL.md가 든 폴더 하나, 그리고 각 Apothem 커맨드마다 폴더 하나(커맨드는 같은 이름의 스킬이 됩니다). |
~/.config/apothem/rules/, ~/.config/apothem/templates/ | 스킬과 규칙 파일이 참조하는 규칙과 템플릿. |
이 폴더들은 공유됩니다. 프로젝트 전용이 아닙니다.
cursor를 설치하는 모든 프로젝트와, 그 폴더를 지정하는 다른 모든 Apothem 설치는 같은 사본을 사용하고 같은 파일을 작성하므로, 설치 순서는 중요하지 않습니다. 다른 여러 도구도~/.agents/skills/를 읽습니다. 하니스 레지스트리가 그 도구들을 나열합니다.--project는 작성할 규칙 파일과 설치가 속하는 프로젝트를 선택합니다. 스킬이 가는 위치는 바꾸지 않습니다.- 설치는 저장소에 스킬 파일이나 규칙 파일을 추가하지 않습니다. 프로젝트에는 규칙
파일,
.cursor/agents/의 서브에이전트 파일,.cursor/hooks.json의 훅 항목, 그리고 모든 프로젝트 설치가 만드는.apothem/폴더가 생기며, 이 폴더에는 훅 스크립트도 들어 있습니다. - 홈 폴더가 먼저 작성됩니다. 예를 들어 경로의 폴더가 홈 디렉터리 밖으로 나가는 링크이거나(홈 안에 머무는 링크는 따라갑니다) 쓸 수 없어서 이 작업이 실패하면, 설치는 프로젝트의 어떤 것도 변경되기 전에 오류와 함께 중단됩니다.
- Apothem 스킬의 이름을 가졌지만 Apothem이 작성하지 않은 스킬 폴더는 그대로 두며,
설치는 그 폴더를 명시하는 경고를 출력합니다. 이름을 바꾸거나 옮긴 다음
apothem update를 실행하세요. 그 이름이 점유되어 있는 동안apothem verify는 실패합니다. - 파일은 모두 합쳐 몇 메가바이트입니다.
설치는 --project 밖에 작성하는 폴더를 명시하는 안내를 출력하며, --dry-run은
그 폴더들을 나열합니다.
서브에이전트
Cursor는 Cursor 서브에이전트 문서에 따라
<project>/.cursor/agents/의 Markdown 파일에서 서브에이전트를 읽습니다. 설치는
그 폴더에 Apothem 도우미마다 파일 하나를 작성합니다. 프로젝트용으로만 설치하며
~/.cursor/agents/ 폴더는 작성하지 않습니다.
각 파일은 도우미의 지침을 변경하지 않고 유지하며 다음 프런트매터 키를 담습니다.
| 키 | Apothem이 작성하는 것 |
|---|---|
name, description | 도우미의 이름과 설명. |
readonly | 도우미 다섯 개에 대해 true: citation-auditor, convention-auditor, fact-checker, memory-auditor, research-scout. |
Cursor에는 도구를 나열하거나 거부하는 키가 없습니다. 서브에이전트는 부모의 모든
도구를 상속합니다. Cursor가 강제할 수 있는 유일한 제한은 readonly: true이며,
이는 파일 편집과 상태를 변경하는 셸 명령을 허용하지 않습니다. 그래서 도우미의
tools 및 disallowedTools 줄은 작성되지 않으며, 제한은 그 플래그로만
남습니다.
- 위의 도우미 다섯 개는 읽기 전용이고
Bash가 없으므로readonly: true를 받으며, 설명에 읽기 전용 문구를 유지합니다. - 도우미 일곱 개는 읽기 전용이지만 명령을 실행합니다(
codebase-explorer,dependency-auditor,design-critic,prompt-evaluator,quality-gate,security-scanner,test-runner).readonly: true는 이들의 테스트와 린트 실행도 막을 것이므로 이들은 플래그를 받지 않으며, 설명에서 Cursor가 강제하지 않을 읽기 전용 레이블을 뺍니다. 설명만 바뀝니다. 지침은 변경 없이 복사되므로 여전히 도우미를 읽기 전용이라고 부르며, Cursor 파일에는 없는 도구 제한을 언급합니다. 모델은 그 텍스트를 따르지만 Cursor는 이를 강제하지 않으며, 도우미는 부모가 가진 모든 도구로 실행됩니다. mcp-builder와refactor-surgeon은 파일을 작성하며 변경되지 않습니다.
설치는 model 키를 작성하지 않으므로 도우미는 부모가 사용하는 모델에서 실행되며,
is_background, 턴 제한, Apothem의 version, updated, portability 키도
작성하지 않습니다.
알아 둘 사항:
- 서브에이전트 파일은 일반 프로젝트 파일입니다. 프로젝트와 함께 커밋하거나
.cursor/agents/를.gitignore에 나열하세요. Apothem은 대신 선택하지 않습니다. - Cursor는 다른 도구용으로 작성된 도우미 폴더도 로드하며, 그중에는 프로젝트의
.claude/agents/와 홈 디렉터리의~/.claude/agents/가 있습니다 (나머지는 하니스 레지스트리에 나열됨). 이름이 충돌하면 프로젝트가 홈 폴더보다 우선하고.cursor/가 다른 폴더보다 우선하므로, 이 설치가 있는 프로젝트에서는 네이티브 파일이 Cursor가~/.claude/agents/에서 가져올 Claude Code 사본을 대체합니다. Cursor의 문서는 두 사본을 모두 로드하는지 아니면 우선순위가 낮은 쪽을 버리는지, 그리고 가져오는 Claude Code 파일의tools및disallowedTools줄을 적용하는지 밝히지 않습니다. - Apothem 도우미의 이름을 가진 여러분의 파일은
~/.apothem/backups/아래에 저장된 다음 교체됩니다. 제거는 그 파일을 되돌려 놓지 않습니다. 다른 이름의 파일은 절대 건드리지 않습니다. - Apothem은 Cursor가 가져오는 폴더에 다른 도구가 작성하는 TOML 파일을 읽는지,
Third-Party Imports 설정이 그 가져온 폴더를 끄는지,
.cursor/agents/에서.md이외의 확장자나 중첩된 폴더를 읽는지 확인하지 않았습니다.
훅
Cursor는 Cursor 훅 문서에 따라 hooks.json
파일에서 훅을 실행합니다. 설치는 <project>/.cursor/hooks.json에 항목 하나를
추가합니다.
| 이벤트 | 실행되는 것 |
|---|---|
sessionStart | 세션 부트스트랩: 세션 메타데이터, 스킬 인덱스, 메모리 및 계획 요약, 상시 자세를 대화의 초기 컨텍스트에 추가합니다. |
훅은 모델에 컨텍스트를 추가합니다. 아무것도 차단하지 않으며, Cursor는
sessionStart 훅을 기다리지 않습니다.
이 첫 버전은 다른 것을 등록하지 않습니다. Cursor의 문서는 postToolUse에
대해서도 additional_context를 나열하며, Apothem은 컨텍스트가 모델에 도달한다는
것을 프로브가 보여 주면 그곳에 컨텍스트 크기 카운터를 등록할 것입니다.
preToolUse 가드는 등록하지 않습니다. Cursor는 가드가 전달 수단으로 쓸 필드인
agent_message를 거부하는 동작에 대해서만 문서화하며, Apothem의 가드는 절대
거부하지 않습니다. 쓰기, 편집, 셸 가드, AskUserQuestion 검사, 세션 종료
프로토콜은 그것들을 전달하는 도구에 남습니다.
파일이 가는 위치
| 파일 | 담고 있는 것 |
|---|---|
<project>/.cursor/hooks.json | 파일의 hooks 맵에 병합된 sessionStart 항목 하나. |
<project>/.apothem/support/cursor/hooks/ | 디스패처 스크립트, 그 보조 스크립트, 메시지 파일. |
hooks.json은 여러분의 파일이며, Cursor는 프로젝트 훅을 버전 관리에 체크인되는
것으로 문서화합니다. 설치는 Apothem의 항목을 여러분의 항목 뒤에 추가하고 여러분의
항목과 다른 키는 그대로 둡니다. 업데이트는 명령이 Apothem 디스패처(어느 프로젝트
경로 아래에 작성되었든 --contract cursor를 붙인
.apothem/support/cursor/hooks/dispatch.py)를 실행하는 항목만 교체하고, 제거는
그 항목만 제거합니다. 프로젝트의 tools/hooks/dispatch.py처럼 이름만 같거나 python -m apothem.conformity.gate를 실행하는 여러분의 훅은 절대 Apothem의 것으로
간주되지 않습니다. 제거는 그 안에 다른 것이 남지 않으면 ~/.apothem/backups/ 아래에
사본을 저장한 뒤 파일을 삭제합니다. 주석, 후행 쉼표, 또는 잘못된 형태의 hooks
값이 있는 파일은 무언가를 잃지 않고는 다시 작성할 수 없으므로, 설치는 그 파일에
대해 config.unparseable 오류를 보고하고, 파일을 건드리지 않은 채 중단하며,
작성하기 시작했던 다른 파일들은 다시 제거합니다. 파일을 고치거나 항목을 직접
추가하세요.
커밋된 파일은 여러분의 머신을 명시합니다. 항목의 명령은 Apothem이 실행될 때
찾은 인터프리터와 프로젝트의 절대 경로를 담으므로, 파일을 체크아웃한 팀원은
여러분의 머신을 가리키는 명령을 받게 됩니다. Cursor는 찾을 수 없는 명령을 실패로
보고하고 세션은 계속되므로 아무것도 깨지지 않지만, 그곳에서 훅은 아무 일도 하지
않습니다. 팀이 그 레이아웃을 공유하는 경우에만 파일을 커밋하세요. Cursor는
프로젝트 훅 파일의 커밋되지 않는 변형을 문서화하지 않습니다. .apothem/ 폴더는
스크립트가 있는 곳이며, 프로젝트의 .gitignore 스니펫이 이를 버전 관리에서
제외합니다.
명령은 다음과 같으며, 두 경로 자리에 여러분의 인터프리터와 프로젝트 경로가 들어갑니다.
"/path/to/python" "/path/to/project/.apothem/support/cursor/hooks/dispatch.py" --contract cursor sessionStartWindows 호스트에서는 명령이 PowerShell의 호출 연산자인 & 로 시작합니다.
Cursor의 데스크톱 앱은 훅 명령을 PowerShell을 통해 실행하는데, PowerShell에서는
따옴표로 묶인 프로그램 경로로 시작하는 줄이 호출이 아니기 때문입니다. sh는
앞의 &를 구문 오류로 읽으므로 다른 호스트는 이를 받지 않습니다. 문서는 셸은
명시하지만 인용 방식은 명시하지 않으므로, 이는 PowerShell 구문에 대한 Apothem의
해석입니다.
--contract cursor는 Cursor의 conversation_id와 workspace_roots를 읽고
{"additional_context": ...}만으로 응답합니다.
셸이 잘못 읽을 경로. $, 백틱, 큰따옴표, 백슬래시가 포함된 프로젝트 또는
인터프리터 경로는 무엇이든 작성되기 전에 거부됩니다. 따옴표로 묶인 명령 안에서
그런 경로는 다른 파일을 실행하거나, 명령이 작성되는 JSON을 깨뜨립니다. 오류는 그
경로를 명시합니다. 프로젝트를 옮기거나 이름을 바꾼 다음 설치를 다시 실행하세요.
경로의 공백이나 아포스트로피는 문제없습니다.
Cursor는 Claude Code가 작성한 훅도 실행합니다. Cursor는 "Include Third-Party
Plugins, Skills, and Other Configs"가 켜져 있는 동안(Cursor Settings의
Third-Party Imports 아래) ~/.claude/settings.json, .claude/settings.json,
.claude/settings.local.json의 훅을 로드하며, 이것이 기본값이고, 모든 소스에서
일치하는 모든 훅을 실행합니다. Claude Code용으로도 Apothem을 설치했다면 두 훅
세트가 모두 실행될 수 있습니다. 여기의 sessionStart 명령과 그 Claude Code
사본은 Apothem의 훅 상태 폴더에서 세션당 마커 하나를 공유하므로, 두 번째로
실행되는 쪽은 아무것도 출력하지 않고 부트스트랩은 모델에 한 번만 도달합니다.
Apothem은 Cursor가 자신의 훅에 설정하는 CURSOR_PROJECT_DIR 및 CURSOR_VERSION
변수로 Cursor를 식별합니다. 마커는 10초 동안 유효하므로, 두 번째 압축처럼 같은
세션이 나중에 다시 시작되면 여전히 전달됩니다. Claude Code 사본의 컨텍스트 크기
카운터는 추가로 실행되며, Apothem은 카운터의 중복을 제거하지 않습니다. 여기의
훅만 실행하려면 그 설정을 끄세요. 그러면 Cursor가 서드파티 플러그인, 스킬, 기타
구성을 가져오는 것도 멈춥니다. 설치는 이를 안내로 출력합니다.
알아 둘 사항. Cursor는 hooks.json이 저장되면 다시 로드하므로 재시작이
필요하지 않습니다. 프로젝트 훅은 신뢰할 수 있는 워크스페이스에서 실행됩니다.
Cursor의 클라우드는 저장소의 프로젝트 훅을 실행하지만 sessionStart를 연기하므로,
그곳에서는 항목이 실행되지 않습니다. Apothem 훅을 끄려면 Cursor의 환경에
APOTHEM_HOOKS_DISABLE=1을 설정하세요.
프로필-네이티브 구성 매핑
어댑터는 apothem install 또는 apothem update를 실행할 때마다 Apothem의
공유 프로필을 읽고 프로젝트 규칙 파일을 렌더링합니다. 공유 프로필이 진실의
원천입니다. 생성된 파일에 대한 프로젝트 로컬 편집은 다음 동기화가 Apothem 관리
콘텐츠를 교체하기 전에 백업됩니다.
Cursor는 규칙의 유형을 파일 시작 부분의 프런트매터에서만 읽으므로, 이 파일은
YAML 프런트매터(description, globs, alwaysApply: true)로 시작합니다.
Apothem 관리 블록이 그 뒤에 오며, 블록 뒤에 여러분이 추가한 텍스트는 동기화할
때마다 유지됩니다.
호환성 참고 사항
Cursor 0.45+는 .cursor/rules/를 통해 프로젝트 수준 지침을 지원합니다.
어댑터는 기본적으로 프로젝트 범위의 .cursor/rules/ 디렉터리에 작성합니다.
Cursor에는 이 어댑터가 관리할 수 있는, 문서화된 파일 기반 사용자 전역 규칙
경로가 없습니다.
Cursor는 ~/.agents/skills/에서 스킬을 로드하므로, 설치가 작성하는 스킬은 추가
설정 없이 Cursor에 나타납니다. Cursor는 ~/.claude/skills/도 로드하므로, Claude
Code 설치도 있는 머신에서는 같은 스킬 이름을 두 번 나열할 수 있으며, 그 문서는
어느 사본이 우선하는지 밝히지 않습니다. Apothem은 Cursor가 자신이 나열하지 않는
SKILL.md 헤더 키를 어떻게 처리하는지 확인하지 않았습니다. 스킬은
user-invocable, disable-model-invocation, allowed-tools, argument-hint,
그리고 metadata 맵을 담습니다.
검증
apothem verify --harness cursor --project /path/to/projectverify 명령은 다음을 확인합니다.
- 네이티브 구성이 예상 경로에 존재합니다.
.cursor/agents/폴더와 훅 파일.cursor/hooks.json을 포함한 각 관리 대상이 존재하고, 관리되는 파일은 비어 있지 않으며, JSON 또는 YAML 구성은 파싱됩니다. 훅 파일에는 Apothem 디스패처를 실행하는 항목이 있어야 하므로(검사는 이를 실행하지 않습니다), 되돌려지거나 비워진 파일은 더 이상 검증을 통과하지 못합니다. 설치된 파일이 그 프로필과도 일치하는지 확인하려면--profile PATH를 추가하세요..cursor/agents/에 대한 검사는 폴더가 존재하는지이며, 각 도우미 파일이 그 안에 있는지가 아닙니다.apothem diff --harness cursor --project /path/to/project는 누락되었거나 오래된 도우미 파일을 나열합니다.- 모든 Apothem 스킬 폴더가 어느 설치가 작성했든
SKILL.md와 함께 제자리에 있고, Apothem 이름을 가진 스킬 폴더 중 Apothem이 작성하지 않은 것에 속하는 폴더는 없습니다. 실패한 검사는 누락되었거나 외부의 폴더를 명시합니다. - 어댑터별 검증 루틴이 성공을 보고합니다.
업데이트
apothem update --harness cursor --project /path/to/project현재 공유 프로필 상태에서 프로젝트 규칙 파일을 다시 도출합니다.
업데이트는 파일이 현재 파일과 다른 스킬 폴더도 다시 작성합니다.
스킬을 작성하지 않던 이전 릴리스로 설치했다면 업데이트가 스킬을 추가합니다.
현재 파일과 다른 서브에이전트 파일을 다시 작성하고, 누락된 파일을 추가합니다.
또한 훅 스크립트와 .cursor/hooks.json의 Apothem 항목을 새로 고치며, 여러분
자신의 항목은 그대로 둡니다.
제거
apothem uninstall --harness cursor --project /path/to/project<project>/.cursor/rules/apothem-rules.mdc에서 Apothem 블록과 Apothem이 그 위에
작성한 프런트매터를 제거하고, 그 안의 나머지 텍스트는 그대로 둡니다. 파일은 그
안에 다른 내용이 하나도 남지 않은 경우에만 삭제됩니다. 변경하기 전에 파일의
타임스탬프가 찍힌 사본이 ~/.apothem/backups/ 아래에 저장되며, 프로젝트에는
백업 파일이 남지 않습니다. 공유 프로필 YAML과 Apothem 엔진은 영향을 받지
않습니다.
제거는 <project>/.cursor/agents/에 작성한 서브에이전트 파일도 제거하고 그곳의
다른 파일은 유지합니다. 폴더는 비게 되면 제거됩니다.
<project>/.cursor/hooks.json에서 Apothem 항목을 명령의 디스패처 경로로
식별하여 제거하고, 여러분 자신의 항목과 키는 유지합니다. 파일은 그 안에 다른
것이 남지 않은 경우에만 삭제됩니다.
<project>/.apothem/support/cursor/hooks/의 훅 스크립트도 제거됩니다.
제거가 읽을 수 없는 주석이 파일에 있으면, 그 파일을 그대로 두고 항목을 건너뛴
것으로 이유와 함께 보고합니다. Apothem 항목을 직접 제거하세요.
~/.agents/skills/에 작성한 스킬 폴더와 ~/.config/apothem/의 규칙 및 템플릿도
제거하지만, 다른 Apothem 설치가 더 이상 사용하지 않을 때만 제거합니다. 다른
프로젝트나 그 폴더를 공유하는 다른 도구가 사용 중일 수 있습니다. 그 경우 제거는
폴더를 유지하고 어느 설치가 사용 중인지 출력하며, 마지막 제거가 폴더를
제거합니다. 그 폴더들에 여러분이 추가한 파일은 남고, 비게 된 폴더는 제거됩니다.
각 폴더는 제거되기 전에 ~/.apothem/backups/ 아래에 백업됩니다.
적합성 게이트
python -m apothem.conformity.gate --all .문제 해결
| 증상 | 해결 방법 |
|---|---|
| 구성 파일을 찾을 수 없음 | apothem install --harness cursor --project /path/to/project를 다시 실행 |
| 검증 실패 | apothem update --harness cursor --project /path/to/project를 실행한 후 다시 검증 |
| Cursor에 Apothem 도우미가 하나도 나열되지 않음 | apothem diff --harness cursor --project /path/to/project를 실행. .cursor/agents 폴더에 대한 보류 중인 줄은 도우미 파일이 누락되었거나 오래되었다는 뜻이므로 apothem update --harness cursor --project /path/to/project를 실행. apothem verify로는 이를 검사할 수 없음: .cursor/agents/가 존재하면 그 안에 도우미 파일이 없어도 통과함. diff가 보류 중인 변경이 없다고 보고하면 프로젝트가 Cursor에서 열려 있는지 확인하고 새 채팅을 시작 |
| Apothem 훅이 실행되지 않음 | Cursor는 신뢰할 수 있는 워크스페이스에서만 프로젝트 훅을 실행함. 항목이 로드되었는지와 무엇을 보고했는지 보려면 Customize의 Hooks 탭이나 Hooks 출력 채널을 열기. 다른 머신에서 작성된 파일은 그 머신의 인터프리터를 명시하므로 Cursor가 명령을 실패로 보고함: 이 머신에서 apothem update --harness cursor --project /path/to/project를 실행 |
설치가 hooks.json에 대해 config.unparseable을 보고함 | 파일에 주석, 후행 쉼표, 또는 잘못된 형태의 hooks 값이 있음. 파일을 고치고 다시 설치하거나, sessionStart 항목을 직접 추가 |
| Apothem 컨텍스트가 두 번 나타남 | Cursor는 Claude Code 설치가 작성한 훅도 실행함. .cursor/hooks.json의 훅만 실행하려면 Cursor Settings의 Third-Party Imports 아래에서 "Include Third-Party Plugins, Skills, and Other Configs"를 끄기 |
apothem verify가 누락된 스킬 폴더를 명시함 | apothem install --harness cursor --project /path/to/project를 실행. 이 명령이 폴더를 복원함 |
| 설치나 업데이트가 스킬 폴더를 건너뛰었다고 경고함 | Apothem 스킬의 이름을 가진 폴더가 이미 스킬 폴더에 있고 Apothem이 작성하지 않았음. 이름을 바꾸거나 옮긴 다음 apothem update를 실행 |
| 설치가 프로젝트를 변경하기 전에 중단됨 | 홈에서의 쓰기가 실패했음. 오류를 읽고, 오류가 명시하는 폴더(홈 디렉터리 밖으로 나가는 링크, 폴더가 있어야 할 자리의 파일, 읽기 전용 폴더)를 고친 다음 다시 설치 |
| 예기치 않은 구성 내용 | ~/.config/apothem/profile.yaml 또는 --profile PATH를 확인한 후 apothem update --harness cursor --project /path/to/project를 다시 실행 |
구성 노브
| 플래그 | 기본값 | 설명 |
|---|---|---|
--dry-run | false | 파일을 작성하지 않고 설치를 미리 봅니다. |
함께 보기
- 전체 하니스 — 지원되는 도구의 전체 카탈로그
- 설치 가이드 — 이 하니스에 Apothem 설치
apothem harnesses참조 — CLI에서 어댑터를 나열하고 검사