GitHub Copilot
GitHub Copilot(GA)용 Apothem 하니스 어댑터.
벤더: GitHub / Microsoft
설치 이름: github-copilot
상태: GA
네이티브 구성: <project>/.github/copilot-instructions.md
설치
apothem install --harness github-copilot --project /path/to/project어댑터는 여러분의 공유 프로필과 공유 Apothem 규칙 및 거버넌스 표면으로부터 프로젝트 지침 파일을 도출하고, Apothem의 도우미를 Copilot 도우미 프로필로 프로젝트에 작성하며(도우미 프로필 참조), 훅 두 개를 등록합니다(훅 참조).
또한 프로젝트를 건드리기 전에 Apothem의 스킬과, 스킬이 인용하는 규칙 및 템플릿을 사용자 홈에 작성합니다(프로젝트 외부의 파일 참조).
작성되는 파일:
<project>/.github/copilot-instructions.md, 지침 파일.- 각 Apothem 도우미마다
<project>/.github/agents/<name>.agent.md, 프로젝트 안. <project>/.github/hooks/apothem.json, 훅 파일, 프로젝트 안. 그 폴더에 있는 여러분 자신의 훅 파일은 건드리지 않습니다.<project>/.apothem/support/github-copilot/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/ | 스킬과 지침 파일이 참조하는 규칙과 템플릿. |
이 폴더들은 공유됩니다. 프로젝트 전용이 아닙니다.
github-copilot을 설치하는 모든 프로젝트와, 그 폴더를 지정하는 다른 모든 Apothem 설치는 같은 사본을 사용하고 같은 파일을 작성하므로, 설치 순서는 중요하지 않습니다. 다른 여러 도구도~/.agents/skills/를 읽습니다. 하니스 레지스트리가 그 도구들을 나열합니다.--project는 작성할 지침 파일과 설치가 속하는 프로젝트를 선택합니다. 스킬이 가는 위치는 바꾸지 않습니다.- 설치는 저장소에 스킬이나 규칙 파일을 추가하지 않습니다. 프로젝트에는
지침 파일,
.github/agents/의 도우미 프로필 파일, 훅 파일.github/hooks/apothem.json, 그리고 모든 프로젝트 설치가 만드는.apothem/폴더가 생기며, 이 폴더에는 훅 스크립트도 들어 있습니다. - 홈 폴더가 먼저 작성됩니다. 예를 들어 경로상의 폴더가 홈 디렉터리 밖으로 나가는 링크이거나(홈 안에 머무는 링크는 따라갑니다) 쓸 수 없어서 이 작업이 실패하면, 설치는 프로젝트에서 무엇이든 변경되기 전에 오류와 함께 중단됩니다.
- Apothem 스킬의 이름을 가졌지만 Apothem이 작성하지 않은 스킬 폴더는 그대로
두며, 설치는 그 폴더를 지목하는 경고를 출력합니다. 이름을 바꾸거나 옮긴 다음
apothem update를 실행하세요. 그 이름이 점유되어 있는 동안apothem verify는 실패합니다. - 파일은 합쳐서 몇 메가바이트 정도입니다.
설치는 --project 밖에 작성하는 폴더를 지목하는 메모를 출력하며,
--dry-run은 그 폴더들을 나열합니다.
도우미 프로필
Copilot은
이 프로필에 대한 GitHub의 참조에
따라 <project>/.github/agents/<name>.agent.md에서 도우미 프로필을 읽습니다.
설치는 Apothem 도우미마다 파일 하나를 그 폴더에 작성합니다. 프로젝트용으로만
설치하며 ~/.copilot/agents/ 폴더는 작성하지 않습니다.
각 파일은 도우미의 지침을 변경 없이 유지하며 다음 프런트매터 키를 담습니다.
| 키 | Apothem이 작성하는 것 |
|---|---|
name, description | 도우미의 이름과 설명. Copilot은 설명을 필요로 합니다. |
tools | 도우미가 사용할 수 있는 도구로, Copilot 도구 별칭의 목록입니다. 예: ["read", "search", "execute"]. |
Copilot의 tools 키는 별칭의 허용 목록이며, 도구를 거부하는 키는 없습니다.
그래서 도우미의 허용 도구와 거부 도구가 하나의 목록으로 합쳐집니다.
| Copilot 별칭 | 포괄하는 도구 | 작성되는 경우: 도우미에게 허용된 도구 |
|---|---|---|
read | Read, NotebookRead | Read |
search | Grep, Glob | Grep 또는 Glob |
edit | Edit, MultiEdit, Write, NotebookEdit | Write, Edit 또는 MultiEdit |
execute | Bash, PowerShell | Bash 또는 PowerShell |
web | WebSearch, WebFetch | WebSearch 또는 WebFetch |
todo | TodoWrite | TodoWrite |
Copilot에는 별칭이 하나 더 있는데, 도우미가 다른 도우미를 시작하게 하는
별칭입니다. 그렇게 하도록 허용된 Apothem 도우미는 없으므로 이 별칭은 결코
작성되지 않습니다. 별칭이 포괄하는 도구 중 하나라도 도우미가 거부하면 그 별칭은
빠집니다. 별칭이 있으면 도우미가 그 도구를 사용할 수 있기 때문입니다. 별칭이
없는 도구(예: Monitor)는 빠집니다. Bash(git status)처럼 패턴이 붙은 도구는
별칭 형식이 없습니다. 허용된 도구로서는 빠지고, 거부된 도구로서는 도구 전체를
거부합니다. 파일을 편집할 수 없는 도우미는 그 제한을 유지합니다. edit를 결코
받지 않습니다.
도우미의 목록에 있는 모든 도구가 빠지면 파일에는 tools: []가 적히며, 이는
도우미에게 도구를 하나도 주지 않습니다. 키를 생략하면 모든 도구를 주게 되므로
생략하지 않습니다.
설치는 model 키를 작성하지 않으므로 도우미는 기본 모델을 사용하며, Copilot이
문서화하는 다른 키(target, disable-model-invocation, user-invocable,
mcp-servers, metadata)도, 턴 제한도, Apothem의 version, updated,
portability 키도 작성하지 않습니다.
알아 둘 사항:
.github/agents/는 저장소의 일부입니다. 팀원과 Copilot의 클라우드 코딩 서비스가 같은 파일을 읽으므로, 프로젝트와 함께 커밋하거나.github/agents/를.gitignore에 나열하세요. Apothem이 대신 선택하지 않습니다.- 클라우드 코딩 서비스는
web과todo별칭을 따르지 않습니다.web별칭은 웹 검색과 페이지 가져오기를 모두 포괄하므로,citation-auditor,fact-checker,research-scout는 그곳에서 파일을 읽고 검색할 수는 있지만 웹을 검색하거나 페이지를 가져올 수는 없습니다. - Copilot CLI는 저장소의
.claude/agents/도 읽지만~/.claude/agents/는 읽지 않으므로, Claude Code 설치는 Copilot에 닿지 않습니다. - Apothem 도우미처럼 이름 붙은(
<name>.agent.md) 여러분의 파일은~/.apothem/backups/아래에 저장된 다음 교체됩니다. 제거는 이를 되돌려 놓지 않습니다. 다른 이름의 파일은 절대 건드리지 않습니다. Copilot의 문서는 폴더에<name>.md와<name>.agent.md가 모두 있을 때 어떻게 되는지 밝히지 않습니다. - Apothem은 한 이름에 대해 Copilot이
.github/agents/와.claude/agents/중 어느 쪽을 우선하는지, 또는 클라우드 코딩 서비스와 VS Code가 자신이 나열하지 않는 프런트매터 키를 어떻게 처리하는지 확인하지 않았습니다.
훅
Copilot은 Copilot 훅 참조에
따라 <project>/.github/hooks/의 JSON 파일에서 훅을 실행합니다. 설치는 그곳에
파일 하나, apothem.json(버전 1)을 작성하며, 훅은 두 개입니다.
| 이벤트 | 실행되는 것 |
|---|---|
sessionStart | 세션 부트스트랩: 세션 메타데이터, 스킬 인덱스, 메모리 및 계획 요약, 상시 자세를 모델의 컨텍스트에 추가합니다. |
postToolUse(모든 도구) | 선제적 압축 추적기. 활동을 세고, 압축 주기당 최대 두 번 모델에게 상태를 저장하거나 압축하라고 알립니다. 그 외에는 아무것도 출력하지 않습니다. |
둘 다 모델에 컨텍스트를 추가합니다. 둘 다 도구 호출이나 세션을 차단하지 않습니다.
Apothem은 Copilot에 preToolUse 가드를 등록하지 않습니다. preToolUse에 대해
Copilot은 권한 필드와 재작성된 도구 입력만 읽으며, additionalContext(Apothem의
가드가 전달 수단으로 쓰는 필드)는 결코 읽지 않습니다. 그곳에 등록된 가드는 도구
호출마다 프로세스 시작 비용을 치르면서 아무것도 전달하지 못하므로, 쓰기, 편집,
셸 가드, AskUserQuestion 검사, 세션 종료 프로토콜은 그것들을 전달하는 도구에
남습니다. 훅은 Copilot의 camelCase 이벤트 이름을 사용합니다. 참조가 그 이름들에
대해 출력 필드를 나열하기 때문입니다. Copilot이 PascalCase 이벤트에서
additionalContext를 읽는지는 문서화되어 있지 않습니다.
파일이 가는 위치
| 파일 | 담고 있는 것 |
|---|---|
<project>/.github/hooks/apothem.json | 두 훅 등록. Apothem은 이 파일 하나를 소유합니다. |
<project>/.apothem/support/github-copilot/hooks/ | 디스패처 스크립트, 그 보조 스크립트, 메시지 파일. |
각 훅에는 bash 명령과 powershell 명령이 있습니다. 둘은 같은 디스패처를
실행하며, powershell 쪽은 앞에 호출 연산자(&)가 붙는데, PowerShell은 따옴표로
묶인 프로그램 경로 앞에 이것이 필요합니다. bash 명령은 다음과 같으며, 두 경로
자리에 여러분의 인터프리터와 프로젝트 경로가 들어갑니다.
"/path/to/python" "/path/to/project/.apothem/support/github-copilot/hooks/dispatch.py" --contract copilot sessionStart--contract copilot은 디스패처가 Copilot의 camelCase 입력을 읽고
{"additionalContext": ...}를 출력하게 하며, 이는 Copilot이 이 두 이벤트에 대해
읽는 형식입니다.
신중하게 커밋하세요, 그리고 클라우드 에이전트. .github/hooks/는 저장소의
일부이며, Copilot의 클라우드 코딩 서비스가 이를 읽습니다. 명령은 Apothem이 실행될
때 찾은 인터프리터와 프로젝트의 절대 경로를 명시하고, 스크립트는 .apothem/에
있는데, 프로젝트의 .gitignore 스니펫이 이를 무시합니다. 다른 어떤 머신에서도,
그리고 클라우드 서비스(bash 명령만 실행함)에서도 명령은 실행할 것을 찾지
못합니다. 실패한 sessionStart 또는 postToolUse 훅은 차단하지 않으므로,
Copilot은 실패를 기록하고 실행은 계속됩니다. .github/hooks/apothem.json을
.gitignore에 추가하거나, 같은 구조를 공유하는 팀에서만 커밋하세요. 설치는
.gitignore를 편집하지 않으며 이를 메모로 출력합니다.
여러분 자신의 훅. .github/hooks/에 있는 여러분의 훅 파일은 절대 읽거나
변경하지 않습니다. 여러분이 apothem.json 자체에 추가한 훅은 유지됩니다.
업데이트와 제거는 명령이 Apothem 디스패처(어느 프로젝트 경로 아래에 작성되었든
--contract copilot을 붙인 .apothem/support/github-copilot/hooks/dispatch.py)를
실행하는 항목만 교체하거나 제거합니다. 이름만 같거나
python -m apothem.conformity.gate를 실행하는 여러분의 훅은 절대 Apothem의 것으로
간주되지 않습니다. 유효한 JSON이 아닌 파일은 ~/.apothem/backups/ 아래에 저장된
다음 교체됩니다.
셸이 잘못 읽을 경로. $, 백틱, 큰따옴표, 백슬래시가 포함된 프로젝트 또는
인터프리터 경로는 무엇이든 작성되기 전에 거부됩니다. 따옴표로 묶인 명령 안에서
그런 경로는 다른 파일을 실행하거나, 명령이 작성되는 JSON을 깨뜨립니다. 오류는 그
경로를 지목합니다. 프로젝트를 옮기거나 이름을 바꾼 다음 설치를 다시 실행하세요.
경로의 공백이나 아포스트로피는 문제없습니다.
훅 끄기. Apothem 훅을 끄려면 Copilot이 실행되는 환경에
APOTHEM_HOOKS_DISABLE=1을 설정하거나, apothem.json에
"disableAllHooks": true를 설정하세요. 후자는 그 파일 하나만 건너뜁니다.
VS Code의 이전 Local 훅 계약(command, windows, linux, osx 필드가 있는
이벤트)은 버전 1 파일이 대상으로 하지 않는 다른 형식입니다.
프로필-네이티브 구성 매핑
어댑터는 apothem install 또는 apothem update를 실행할 때마다 Apothem의
공유 프로필을 읽고 저장소 전체에 적용되는 Copilot 지침 파일을 렌더링합니다.
공유 프로필이 진실의 원천입니다. 생성된 파일에 대한 프로젝트 로컬 편집은 다음
동기화가 Apothem 관리 콘텐츠를 교체하기 전에 백업됩니다.
Apothem 블록 안에서는 여러분의 프로필로부터 렌더링된 섹션(운영자, 선호, 사용자 지정 규칙, 옵트인한 동작, MCP 서버 이름)이 공유 거버넌스 텍스트보다 앞에 옵니다. GitHub는 지침 파일이 짧을수록 코드 리뷰가 파일 전체를 처리할 가능성이 높다고 설명하므로 (코드 리뷰 사용자 지정), 여러분에게 특화된 부분이 파일의 맨 앞에 옵니다.
호환성 참고 사항
GitHub Copilot은 이 어댑터가 관리할 수 있는 파일 기반 사용자 전역 지침 경로를
노출하지 않습니다. Apothem은 문서화된 프로젝트 범위 지침 파일을 대상으로 하며,
IDE 수준의 사용자 설정은 운영자 소유로 남겨 둡니다. 훅 파일
.github/hooks/apothem.json 하나를 작성하며, .github/hooks/의 다른 파일은
작성하지 않습니다.
Apothem 저장소 안에서 .github/copilot-instructions.md는 그 저장소의 어시스턴트
지침 표면 가운데 하나의 목소리입니다. 해당 저장소의 체크아웃에서 적합성 게이트의
다중 표면 일관성 검사는 AGENTS.md, CLAUDE.md,
.github/copilot-instructions.md에 담긴 공유 주장을 비교합니다. 이 검사는 세
파일 가운데 하나가 빠뜨린 공유 주장과, AGENTS.md가 내세우는 주장에 모순되는
파일을 보고합니다. 이 검사는 Apothem이 여러분의 프로젝트에 작성하는 지침 파일을
읽지 않습니다. 이 게이트는 기본적으로 권고용입니다. 결과를 보고하고 0으로
종료합니다.
GitHub Copilot은 개인 스킬 위치 가운데 하나로 ~/.agents/skills/를 나열하므로,
설치가 작성하는 스킬은 Copilot이 로드할 수 있도록 여러분의 머신에 있습니다.
GitHub에서 실행되는 표면인 클라우드 코딩 서비스와 코드 리뷰는 다른 곳에서
실행되어 여러분의 홈 폴더를 보지 못하며, 이것이 지침 파일이 규율 자체를 담는
이유입니다. Apothem은 Copilot이 자신이 나열하지 않는 SKILL.md 헤더 키를 어떻게
처리하는지 확인하지 않았습니다. 스킬은 user-invocable,
disable-model-invocation, allowed-tools, argument-hint, 그리고 metadata
맵을 담습니다.
검증
apothem verify --harness github-copilot --project /path/to/projectverify 명령은 다음을 확인합니다.
- 네이티브 구성이 예상 경로에 존재합니다.
.github/agents/폴더를 포함해 각 관리 대상이 존재하고, 관리되는 파일은 비어 있지 않으며, JSON 또는 YAML 구성은 파싱됩니다. 설치된 파일이 그 프로필과도 일치하는지 확인하려면--profile PATH를 추가하세요..github/agents/에 대해서는 각 도우미 파일이 그 안에 있는지가 아니라 폴더가 존재하는지를 확인합니다.apothem diff --harness github-copilot --project /path/to/project명령은 누락되었거나 오래된 도우미 파일을 나열합니다. 훅 파일.github/hooks/apothem.json은 존재하고, 비어 있지 않고, JSON으로 파싱되며, Apothem 디스패처를 실행하는 항목을 담고 있어야 하고, 훅 스크립트는.apothem/support/github-copilot/hooks/에 있어야 합니다. 검사는 훅을 실행하지 않습니다.- 어느 설치가 작성했든 모든 Apothem 스킬 폴더가
SKILL.md와 함께 제자리에 있으며, Apothem 이름을 가진 스킬 폴더 중 Apothem이 작성하지 않은 것에 속하는 폴더가 없습니다. 확인이 실패하면 누락되었거나 외부의 폴더를 지목합니다. - 어댑터별 검증 루틴이 성공을 보고합니다.
업데이트
apothem update --harness github-copilot --project /path/to/project현재 공유 프로필 상태에서 프로젝트 지침 파일을 다시 도출합니다.
업데이트는 또한 파일이 현재 파일과 다른 스킬 폴더를 다시 작성합니다.
스킬을 작성하지 않던 이전 릴리스로 설치했다면 업데이트가 스킬을 추가합니다.
현재 파일과 다른 도우미 프로필 파일을 다시 작성하고, 누락된 파일은 추가합니다.
또한 훅 스크립트와 .github/hooks/apothem.json의 Apothem 훅을 새로 고치며,
그 파일에 있는 여러분의 훅은 유지합니다.
제거
apothem uninstall --harness github-copilot --project /path/to/project<project>/.github/copilot-instructions.md에서 Apothem 블록을 제거하고, 그
바깥의 텍스트는 그대로 둡니다. 파일에 다른 내용이 남아 있지 않을 때에만 파일을
삭제합니다. 변경하기 전에 파일의 타임스탬프가 찍힌 사본이
~/.apothem/backups/ 아래에 저장됩니다. 공유 프로필 YAML과 Apothem 엔진은
영향을 받지 않습니다.
제거는 또한 <project>/.github/agents/에 작성한 도우미 프로필 파일을 제거하고
그곳의 다른 파일은 유지합니다. 폴더가 비게 되면 폴더를 제거합니다.
<project>/.github/hooks/apothem.json에서 Apothem 훅을 명령의 디스패처 경로로
식별하여 제거하므로 설치 기록 없이도 작동하며, 그 파일에 있는 여러분의 훅은
유지합니다. 파일은 그 안에 다른 것이 없으면 삭제되며, 여러분의 다른 훅 파일은
건드리지 않습니다. 파일에 제거가 읽을 수 없는 주석이 있으면, 파일을 그대로 두고
훅을 건너뛴 것으로 이유와 함께 보고합니다. Apothem 항목은 직접 제거하세요.
<project>/.apothem/support/github-copilot/hooks/의 훅 스크립트도 제거됩니다.
~/.agents/skills/에 작성한 스킬 폴더와 ~/.config/apothem/의 규칙 및 템플릿도
제거하지만, 다른 Apothem 설치가 더 이상 사용하지 않을 때만 제거합니다. 다른
프로젝트나 그 폴더를 공유하는 다른 도구가 사용하고 있을 수 있습니다. 그런 경우
제거는 폴더를 유지하고 어느 설치가 사용 중인지 출력하며, 마지막 제거가 폴더를
제거합니다. 그 폴더에 여러분이 추가한 파일은 남으며, 비게 된 폴더는 제거됩니다.
각 폴더는 제거되기 전에 ~/.apothem/backups/ 아래에 백업됩니다.
적합성 게이트
python -m apothem.conformity.gate --all .--all 실행은 독립형 검증기를 대상으로 합니다. 호환성 참고 사항에 설명된 다중 표면 일관성 검사는 실행하지 않습니다. 체크아웃에서 이 검사를 이름으로 실행하려면 다음을 사용하세요:
python -m apothem.conformity.gate --check multi-surface-coherence-grep AGENTS.md문제 해결
| 증상 | 해결 방법 |
|---|---|
| 구성 파일을 찾을 수 없음 | apothem install --harness github-copilot --project /path/to/project를 다시 실행 |
| 검증 실패 | apothem update --harness github-copilot --project /path/to/project를 실행한 후 다시 검증 |
| Copilot이 Apothem 도우미를 하나도 나열하지 않음 | .github/agents/에 .agent.md 파일이 있고 그 파일들이 사용 중인 브랜치에 있는지 확인. apothem diff --harness github-copilot --project /path/to/project를 실행: .github/agents 폴더에 대한 보류 줄은 도우미 파일이 누락되었거나 오래되었다는 뜻이므로, apothem update --harness github-copilot --project /path/to/project를 실행. apothem verify는 이를 검사하지 않음: 도우미 파일이 하나도 없어도 .github/agents/가 존재하면 통과함 |
| Apothem 훅이 실행되지 않음 | .github/hooks/apothem.json이 사용 중인 브랜치에 있고 이 머신에 .apothem/support/github-copilot/hooks/가 존재하는지 확인. 명령은 설치를 실행한 머신의 인터프리터와 프로젝트 경로를 명시하므로, 각 머신에서 apothem install --harness github-copilot --project /path/to/project를 실행. Copilot의 클라우드 코딩 서비스는 bash 명령만 실행하며, 그 경로에 인터프리터가 없음 |
apothem verify가 누락된 스킬 폴더를 지목함 | apothem install --harness github-copilot --project /path/to/project를 실행. 폴더를 복원합니다 |
| 설치 또는 업데이트가 스킬 폴더를 건너뛰었다고 경고함 | Apothem 스킬의 이름을 가진 폴더가 스킬 폴더에 이미 있고 Apothem이 작성하지 않았습니다. 이름을 바꾸거나 옮긴 다음 apothem update를 실행 |
| 설치가 프로젝트를 변경하기 전에 중단됨 | 홈에서의 쓰기가 실패했습니다. 오류를 읽고 지목된 폴더(홈 디렉터리 밖으로 나가는 링크, 폴더가 있어야 할 자리의 파일, 또는 읽기 전용 폴더)를 고친 다음 다시 설치 |
| 예기치 않은 구성 내용 | ~/.config/apothem/profile.yaml 또는 --profile PATH를 확인한 후 apothem update --harness github-copilot --project /path/to/project를 다시 실행 |
구성 노브
| 플래그 | 기본값 | 설명 |
|---|---|---|
--dry-run | false | 파일을 작성하지 않고 설치를 미리 봅니다. |
함께 보기
- 전체 하니스 — 지원되는 도구의 전체 카탈로그
- 설치 가이드 — 이 하니스에 Apothem 설치
apothem harnesses참조 — CLI에서 어댑터를 나열하고 검사