Kiro
Kiro(GA)용 Apothem 하니스 어댑터.
벤더: AWS
설치 이름: kiro
상태: GA
네이티브 구성: <project>/.kiro/steering/apothem-rules.md
설치
apothem install --harness kiro --project /path/to/project어댑터는 공유 Apothem 규칙과 거버넌스 표면으로부터 프로젝트 범위의 Kiro 스티어링 파일 하나를 작성하고, Apothem의 도우미를 Kiro 사용자 정의 에이전트 파일로 프로젝트에 작성하며(사용자 정의 에이전트 파일 참조), 훅 하나를 작성합니다(훅 참조).
또한 프로젝트를 건드리기 전에 Apothem의 스킬과, 스킬이 인용하는 규칙 및 템플릿을 사용자 홈에 작성합니다(프로젝트 외부의 파일 참조).
작성되는 파일:
<project>/.kiro/steering/apothem-rules.md, 스티어링 파일.- 각 Apothem 도우미마다
<project>/.kiro/agents/<name>.md, 프로젝트 안. <project>/.kiro/hooks/apothem.json, 훅 파일, 프로젝트 안. 그 폴더에 있는 여러분 자신의 훅 파일은 건드리지 않습니다.<project>/.apothem/support/kiro/hooks/, 훅 스크립트, 프로젝트 안.- 각 Apothem 스킬과 커맨드마다
~/.kiro/skills/<name>/SKILL.md, 사용자 홈 안. ~/.config/apothem/rules/와~/.config/apothem/templates/, 사용자 홈 안.
프로젝트 외부의 파일
설치는 프로젝트에서 무엇이든 변경하기 전에 Apothem의 스킬도 사용자 홈에 작성합니다.
| 폴더 | Apothem이 그곳에 작성하는 것 |
|---|---|
~/.kiro/skills/ | 각 Apothem 스킬마다 SKILL.md가 든 폴더 하나, 그리고 각 Apothem 커맨드마다 폴더 하나(커맨드는 같은 이름의 스킬이 됩니다). |
~/.config/apothem/rules/, ~/.config/apothem/templates/ | 스킬과 스티어링 파일이 참조하는 규칙과 템플릿. |
이 폴더들은 공유됩니다. 프로젝트 전용이 아닙니다.
kiro를 설치하는 모든 프로젝트는 같은~/.kiro/skills/사본을 사용하며, 설치는 매번 같은 파일을 그곳에 작성합니다. 그 폴더를 읽는 도구는 Kiro뿐입니다.~/.config/apothem/아래의 규칙과 템플릿은 다른 도구의 설치도 같은 파일로 작성합니다.--project는 작성할 스티어링 파일과 설치가 속하는 프로젝트를 선택합니다. 스킬이 가는 위치는 바꾸지 않습니다.- 설치는 저장소에 스킬이나 규칙 파일을 추가하지 않습니다. 프로젝트에는
스티어링 파일,
.kiro/agents/의 사용자 정의 에이전트 파일, 훅 파일.kiro/hooks/apothem.json, 그리고 모든 프로젝트 설치가 만드는.apothem/폴더가 생기며, 이 폴더에는 훅 스크립트도 들어 있습니다. - 홈 폴더가 먼저 작성됩니다. 예를 들어 경로상의 폴더가 홈 디렉터리 밖으로 나가는 링크이거나(홈 안에 머무는 링크는 따라갑니다) 쓸 수 없어서 이 작업이 실패하면, 설치는 프로젝트에서 무엇이든 변경되기 전에 오류와 함께 중단됩니다.
- Apothem 스킬의 이름을 가졌지만 Apothem이 작성하지 않은 스킬 폴더는 그대로
두며, 설치는 그 폴더를 지목하는 경고를 출력합니다. 이름을 바꾸거나 옮긴 다음
apothem update를 실행하세요. 그 이름이 점유되어 있는 동안apothem verify는 실패합니다. - 파일은 합쳐서 몇 메가바이트 정도입니다.
설치는 --project 밖에 작성하는 폴더를 지목하는 메모를 출력하며,
--dry-run은 그 폴더들을 나열합니다.
사용자 정의 에이전트 파일
Kiro는 Kiro 사용자 정의 에이전트 문서에
따라 <project>/.kiro/agents/의 Markdown 파일에서 사용자 정의 에이전트를
읽습니다. 설치는 Apothem 도우미 열네 개 모두에 대해 도우미마다 파일 하나를 그
폴더에 작성합니다. 대상은 Markdown 형식을 읽는 버전인 Kiro IDE 1.0과 Kiro CLI
V3(kiro-cli --v3)입니다. V3는 allowedTools가 있고 permissions 블록이 없는
JSON 프로필을 건너뛰므로, 설치는 JSON 프로필도, 이전 CLI 2.x 키도 작성하지
않습니다. 프로젝트용으로만 설치합니다. 사용자 폴더 ~/.kiro/agents/는 작성하지 않습니다.
각 파일은 도우미의 지침을 변경 없이 유지하며 다음 프런트매터 키를 담습니다.
| 키 | Apothem이 작성하는 것 |
|---|---|
name, description | 도우미의 이름과 설명. Kiro의 메인 에이전트는 설명을 보고 도우미를 고릅니다. |
tools | 도우미가 사용할 수 있는 도구로, Kiro 도구 범주의 목록입니다: ["read", "shell"]. 도우미가 아무것도 제한하지 않으면 생략됩니다. |
Kiro에는 도구 목록이 하나뿐이므로, 도우미의 허용 도구와 거부 도구가 그 목록이
됩니다. 범주는 read, write, shell, web, subagent입니다.
| 도우미의 도구 | Kiro 범주 |
|---|---|
Read, Glob, Grep | read |
Write, Edit, MultiEdit, NotebookEdit | write |
Bash, PowerShell | shell |
WebSearch, WebFetch | web |
Agent, Task | subagent |
범주가 없는 도구(TodoWrite, Monitor, Artifact, TaskCreate,
TaskUpdate, MCP 항목)는 빠집니다. 도우미가 어떤 범주의 도구 하나라도 거부당했으면
그 범주는 빠지므로, 도우미는 거부된 도구를 결코 얻지 못합니다. 파일을 편집할 수
없는 도우미는 write 범주를 받지 않습니다. 허용 도구가 모두 빠진 도우미는
tools: []로 작성되므로, 모든 도구를 받지 않습니다. 도우미 두 개
(mcp-builder와 refactor-surgeon)가 write를, 아홉 개가 shell을, 세 개가
web을 담습니다. 설치는 model 키를 작성하지 않으므로 도우미는 Kiro가 선택한
모델에서 실행되며, permissions, excludedTools, resources, mcpServers,
hooks 중 어느 것도 작성하지 않습니다.
알아 둘 사항:
- Kiro는 여러분이 워크스페이스를 신뢰하기 전까지 워크스페이스의 사용자 정의 에이전트 파일을 로드하지 않습니다. Kiro CLI 2.33 이상은 한 폴더에서 처음 대화형 V3 세션을 시작할 때 "Trust this workspace?"라고 묻습니다. Kiro가 도우미를 하나도 나열하지 않으면 그 폴더를 신뢰하고 새 세션을 시작하세요.
- Apothem은 Kiro CLI 2.x가 V3 Markdown 에이전트를 로드하는지 확인하지 않았습니다.
IDE를 사용하거나
kiro-cli --v3를 실행하세요. - 에이전트 파일은 일반 프로젝트 파일입니다. 프로젝트와 함께 커밋하거나
.kiro/agents/를.gitignore에 나열하세요. Apothem이 대신 선택하지 않습니다. - Apothem 도우미의 이름을 가진 여러분의 파일은
~/.apothem/backups/아래에 저장된 다음 교체됩니다. 제거는 이를 되돌려 놓지 않습니다. JSON 프로필을 포함해 다른 이름의 파일은 절대 건드리지 않습니다. - 사용자 정의 에이전트가 기본적으로
~/.kiro/skills/의 스킬을 보는지에 대해 Kiro의 페이지들은 서로 다르게 말합니다. 스킬 페이지는 에이전트에skill://리소스가 필요하다고 하는 반면, 구성 참조는 에이전트가 기본 스킬을 상속한다고 합니다. 설치는resources키를 추가하지 않으므로, 두 번째 해석이 맞을 때에만 도우미가 스킬을 봅니다. - Kiro의 Built-in tools 페이지는 각 범주가
일반적으로 포함하는 도구를 나열합니다.
read범주는 파일 검색 및 텍스트 검색 도구(CLI 2.x의glob과grep)를 포함하며, 이것이Glob과Grep이 그곳에 매핑되는 이유입니다. 또한code(구문 트리에 의한 코드 분석)와introspect(Kiro 자체에 관한 질문에 답함)도 포함하므로,read를 가진 도우미는 둘 다 사용할 수 있습니다. 이 페이지는code를write아래에도 나열하며, 그 도구가 파일을 편집하는지는 밝히지 않습니다. - Apothem은
tools키가 생략되었을 때 Kiro가 어떻게 하는지, 또는 Kiro가name외에 어떤 프런트매터 키를 요구하는지 확인하지 않았습니다.
훅
Kiro는 Kiro 훅 문서에 따라
<project>/.kiro/hooks/의 JSON 파일에서 훅을 실행합니다. 설치는 그곳에 파일
하나, apothem.json(훅 파일 버전 v1)을 작성하며, 훅은 하나입니다.
| 트리거 | 실행되는 것 |
|---|---|
SessionStart | 세션 부트스트랩: 세션 메타데이터, 스킬 인덱스, 메모리 및 계획 요약, 상시 자세를 모델의 컨텍스트에 추가합니다. |
이 훅은 모델에 컨텍스트를 추가합니다. 도구 호출이나 세션을 차단하지 않습니다.
Apothem은 Kiro에 PreToolUse나 PostToolUse 훅을 등록하지 않습니다. Kiro는
SessionStart와 UserPromptSubmit에 대해서만 명령의 출력을 모델의 컨텍스트에
추가하고, 도구 이벤트에 대해서는 이를 무시합니다. 도구 이벤트에 등록된 가드는
도구 호출마다 프로세스 시작 비용을 치르면서 아무것도 전달하지 못하므로, 쓰기,
편집, 셸 가드, 컨텍스트 크기 안내, 세션 종료 프로토콜은 그것들을 전달하는 도구에
남습니다. 설치는 UserPromptSubmit용 훅을 작성하지 않으며, 사용자 폴더
~/.kiro/hooks/에 훅을 작성하지 않습니다.
파일이 가는 위치
| 파일 | 담고 있는 것 |
|---|---|
<project>/.kiro/hooks/apothem.json | 훅 등록. Apothem은 이 파일 하나를 소유합니다. |
<project>/.apothem/support/kiro/hooks/ | 디스패처 스크립트, 그 보조 스크립트, 메시지 파일. |
훅 파일의 명령은 다음과 같으며, 두 경로 자리에 여러분의 인터프리터와 프로젝트 경로가 들어갑니다.
"/path/to/python" "/path/to/project/.apothem/support/kiro/hooks/dispatch.py" --contract kiro SessionStart--contract kiro는 디스패처가 컨텍스트를 일반 텍스트로 출력하게 하며, 이는
Kiro가 SessionStart에 대해 컨텍스트에 추가하는 형식입니다. Kiro는 Windows에서
명령 동작에 쓰이는 셸을 문서화하지 않습니다. 명령은 sh와 cmd.exe용으로
작성되며, 인터프리터 경로는 슬래시를 쓰고 따옴표로 묶입니다. 여러분의 머신에서
Kiro가 이를 PowerShell에서 실행한다면, 따옴표로 묶인 경로 앞에 호출 연산자(&)가
필요하며, 이를 직접 추가할 수 있습니다.
워크스페이스를 신뢰하세요. Kiro CLI 2.33 이상은 여러분이 워크스페이스를
신뢰한 뒤에만 워크스페이스의 훅을 로드합니다. 한 폴더에서 처음 대화형 V3
세션(kiro-cli --v3)을 시작할 때 "Trust this workspace?"라고 묻습니다. Kiro Web
세션은 훅을 실행하지 않습니다. 설치는 이를 메모로 출력합니다.
신중하게 커밋하세요. 명령은 Apothem이 실행될 때 찾은 인터프리터와 프로젝트의
절대 경로를 명시하므로 파일은 여러분의 머신에 종속되며, 명령이 실행하는
스크립트는 .apothem/에 있는데, 프로젝트의 .gitignore 스니펫이 이를
무시합니다. .kiro/hooks/apothem.json을 커밋하면 팀원의 체크아웃은 아무것도
가리키지 않는 훅을 받습니다. Kiro는 실패한 명령에 대해 경고를 표시하고 세션은
계속됩니다. .kiro/hooks/apothem.json을 .gitignore에 추가하거나, 같은 구조를
공유하는 팀에서만 커밋하세요. 설치는 .gitignore를 편집하지 않습니다.
여러분 자신의 훅. .kiro/hooks/에 있는 여러분의 훅 파일은 절대 읽거나
변경하지 않습니다. 여러분이 apothem.json 자체에 추가한 훅은 유지됩니다.
업데이트와 제거는 명령이 Apothem 디스패처(어느 프로젝트 경로 아래에 작성되었든
--contract kiro를 붙인 .apothem/support/kiro/hooks/dispatch.py)를 실행하는
훅만 교체하거나 제거합니다. 이름만 같거나 python -m apothem.conformity.gate를
실행하는 여러분의 훅은 절대 Apothem의 것으로 간주되지 않습니다. 유효한 JSON이
아닌 파일은 ~/.apothem/backups/ 아래에 저장된 다음 교체됩니다.
셸이 잘못 읽을 경로. $, 백틱, 큰따옴표, 백슬래시가 포함된 프로젝트 또는
인터프리터 경로는 무엇이든 작성되기 전에 거부됩니다. 따옴표로 묶인 명령 안에서
그런 경로는 다른 파일을 실행하거나, 명령이 작성되는 JSON을 깨뜨립니다. 오류는 그
경로를 지목합니다. 프로젝트를 옮기거나 이름을 바꾼 다음 설치를 다시 실행하세요.
경로의 공백이나 아포스트로피는 문제없습니다.
훅 끄기. Apothem 훅을 끄려면 Kiro의 환경에 APOTHEM_HOOKS_DISABLE=1을
설정하세요. 업데이트는 Apothem 항목을 다시 작성하므로 그 항목에 대한 편집은
유지되지 않지만, 한 가지 예외가 있습니다. 항목에 "enabled": false를 설정하면,
Kiro는 이를 훅을 삭제하지 않고 건너뛰는 것으로 문서화하며, 업데이트는 이 설정을
유지합니다.
프로필-네이티브 구성 매핑
어댑터는 Apothem의 공유 프로필을 읽고 매 apothem install 또는 apothem update
실행마다 프로젝트 스티어링 파일을 렌더링합니다. 공유 프로필이 진실의
원천입니다. 생성된 파일에 대한 프로젝트 로컬 편집은 다음 동기화가 Apothem 관리
콘텐츠를 교체하기 전에 백업됩니다.
이 파일은 inclusion: always 프런트매터로 시작합니다. Kiro는 inclusion 구성이
파일의 첫 번째 콘텐츠여야 한다고 요구하기 때문입니다. Apothem 관리 블록이 그
뒤에 오며, 블록 뒤에 여러분이 추가한 텍스트는 매 동기화 때 유지됩니다.
호환성 참고 사항
Kiro의 스티어링 표면은 .kiro/steering/ 아래에서 프로젝트 범위로 지정됩니다.
어댑터는 inclusion: always 프런트매터가 있는 전용 apothem-rules.md 스티어링
파일을 작성하며, 운영자가 작성한 Kiro의 기초 파일(product.md, tech.md,
structure.md)을 절대 덮어쓰지 않습니다. Kiro 스펙(.kiro/specs/)은
운영자 소유입니다. Apothem은 이를 작성하지 않습니다. 훅 파일
.kiro/hooks/apothem.json 하나를 작성하며, .kiro/hooks/의 다른 파일은 작성하지
않습니다.
Kiro는 전역 스킬용으로 ~/.kiro/skills/를 문서화하고 ~/.agents/skills/는
언급하지 않으므로, 설치는 도구 간 공용 폴더가 아니라 Kiro 폴더에 작성합니다.
같은 이름의 워크스페이스 스킬이 전역 스킬보다 우선합니다. Apothem은 Kiro가
나열하지 않은 SKILL.md 헤더 키를 어떻게 처리하는지 확인하지 않았습니다.
검증
apothem verify --harness kiro --project /path/to/projectverify 명령은 다음을 확인합니다.
- 네이티브 구성이 예상 경로에 존재합니다.
.kiro/agents/폴더를 포함해 각 관리 대상이 존재하고, 관리되는 파일은 비어 있지 않으며, JSON 또는 YAML 구성은 파싱됩니다. 설치된 파일이 그 프로필과도 일치하는지 확인하려면--profile PATH를 추가하세요..kiro/agents/에 대해서는 각 도우미 파일이 그 안에 있는지가 아니라 폴더가 존재하는지를 확인합니다.apothem diff --harness kiro --project /path/to/project명령은 누락되었거나 오래된 도우미 파일을 나열합니다. 훅 파일.kiro/hooks/apothem.json은 존재하고, 비어 있지 않고, JSON으로 파싱되며, Apothem 디스패처를 실행하는 훅을 담고 있어야 하고, 훅 스크립트는.apothem/support/kiro/hooks/에 있어야 합니다. 검사는 훅을 실행하지 않습니다.- 어느 설치가 작성했든 모든 Apothem 스킬 폴더가
SKILL.md와 함께 제자리에 있으며, Apothem 이름을 가진 스킬 폴더 중 Apothem이 작성하지 않은 것에 속하는 폴더가 없습니다. 확인이 실패하면 누락되었거나 외부의 폴더를 지목합니다. - 어댑터별 검증 루틴이 성공을 보고합니다.
업데이트
apothem update --harness kiro --project /path/to/project현재 공유 프로필 상태에서 프로젝트 스티어링 파일을 다시 도출합니다.
업데이트는 또한 파일이 현재 파일과 다른 스킬 폴더를 다시 작성합니다.
스킬을 작성하지 않던 이전 릴리스로 설치했다면 업데이트가 스킬을 추가합니다.
현재 파일과 다른 사용자 정의 에이전트 파일을 다시 작성하고, 누락된 파일은 추가합니다.
또한 훅 스크립트와 .kiro/hooks/apothem.json의 Apothem 훅을 새로 고치며,
그 파일에 있는 여러분의 훅은 유지합니다.
제거
apothem uninstall --harness kiro --project /path/to/project<project>/.kiro/steering/apothem-rules.md에서 Apothem 블록과 그 위에 Apothem이
작성한 프런트매터를 제거하고, 파일 안의 나머지 텍스트는 그대로 둡니다. 파일에
다른 내용이 남아 있지 않을 때에만 파일을 삭제합니다. 변경하기 전에 파일의
타임스탬프가 찍힌 사본이 ~/.apothem/backups/ 아래에 저장되며, 프로젝트에는
백업 파일이 남지 않습니다. 공유 프로필 YAML과 Apothem 엔진은 영향을 받지
않습니다.
제거는 또한 <project>/.kiro/agents/에 작성한 사용자 정의 에이전트 파일을
제거하고 그곳의 다른 파일은 유지합니다. 폴더가 비게 되면 폴더를 제거합니다.
<project>/.kiro/hooks/apothem.json에서 Apothem 훅을 명령의 디스패처 경로로
식별하여 제거하므로 설치 기록 없이도 작동하며, 그 파일에 있는 여러분의 훅은
유지합니다. 파일은 그 안에 다른 것이 없으면 삭제되며, 여러분의 다른 훅 파일은
건드리지 않습니다. 파일에 제거가 읽을 수 없는 주석이 있으면, 파일을 그대로 두고
훅을 건너뛴 것으로 이유와 함께 보고합니다. Apothem 훅은 직접 제거하세요.
<project>/.apothem/support/kiro/hooks/의 훅 스크립트도 제거됩니다.
~/.kiro/skills/에 작성한 스킬 폴더와 ~/.config/apothem/의 규칙 및 템플릿도
제거하지만, 다른 Apothem 설치가 더 이상 사용하지 않을 때만 제거합니다. 다른
프로젝트나 그 폴더를 공유하는 다른 도구가 사용하고 있을 수 있습니다. 그런 경우
제거는 폴더를 유지하고 어느 설치가 사용 중인지 출력하며, 마지막 제거가 폴더를
제거합니다. 그 폴더에 여러분이 추가한 파일은 남으며, 비게 된 폴더는 제거됩니다.
각 폴더는 제거되기 전에 ~/.apothem/backups/ 아래에 백업됩니다.
적합성 게이트
python -m apothem.conformity.gate --all .문제 해결
| 증상 | 해결 방법 |
|---|---|
| 구성 파일을 찾을 수 없음 | apothem install --harness kiro --project /path/to/project를 다시 실행 |
| 검증 실패 | apothem update --harness kiro --project /path/to/project를 실행한 후 다시 검증 |
| Kiro가 Apothem 도우미를 하나도 나열하지 않음 | 워크스페이스를 신뢰(CLI는 한 폴더에서 처음 대화형 V3 세션을 시작할 때 "Trust this workspace?"라고 물음)하고, IDE 또는 kiro-cli --v3를 사용 |
| Apothem 훅이 실행되지 않음 | 워크스페이스를 신뢰(CLI는 한 폴더에서 처음 대화형 V3 세션을 시작할 때 "Trust this workspace?"라고 물음)하고, IDE 또는 kiro-cli --v3를 사용. Kiro Web 세션은 훅을 실행하지 않음. 세션 시작 시 명령에 대한 경고가 나오면 이 머신에 인터프리터나 .apothem/support/kiro/hooks/ 폴더가 없다는 뜻이므로, 그 머신에서 apothem install --harness kiro --project /path/to/project를 실행 |
apothem verify가 누락된 스킬 폴더를 지목함 | apothem install --harness kiro --project /path/to/project를 실행. 폴더를 복원합니다 |
| 설치 또는 업데이트가 스킬 폴더를 건너뛰었다고 경고함 | Apothem 스킬의 이름을 가진 폴더가 스킬 폴더에 이미 있고 Apothem이 작성하지 않았습니다. 이름을 바꾸거나 옮긴 다음 apothem update를 실행 |
| 설치가 프로젝트를 변경하기 전에 중단됨 | 홈에서의 쓰기가 실패했습니다. 오류를 읽고 지목된 폴더(홈 디렉터리 밖으로 나가는 링크, 폴더가 있어야 할 자리의 파일, 또는 읽기 전용 폴더)를 고친 다음 다시 설치 |
| 예기치 않은 구성 내용 | ~/.config/apothem/profile.yaml 또는 --profile PATH를 확인한 후 apothem update --harness kiro --project /path/to/project를 다시 실행 |
구성 노브
| 플래그 | 기본값 | 설명 |
|---|---|---|
--dry-run | false | 파일을 작성하지 않고 설치를 미리 봅니다. |
함께 보기
- 전체 하니스 — 지원되는 도구의 전체 카탈로그
- 설치 가이드 — 이 하니스에 Apothem 설치
apothem harnesses참조 — CLI에서 어댑터를 나열하고 검사