개념

현재 릴리스에는 에이전트 15개, 스킬 15개, 규칙 12개가 들어 있습니다. 이 페이지는 그것들이 무엇을 위해 있는지 설명합니다. 경로는 hiway-kit 레포의 plugins/common/ 기준입니다.

네이티브 우선#

Claude Code에는 이미 에이전트·스킬·훅·워크플로·텔레메트리·메모리가 있고, 거의 매주 바뀝니다. 이런 킷에서 가장 큰 부채는 하네스가 이미 하는 일을 다시 구현하는 것입니다. 그래서 hiway-kit은 관측·위임·훅 실행 같은 인프라는 하네스에 맡기고, 그 위에 의견이 담긴 층(에이전트·스킬·규율)만 얹습니다. 네이티브 기능이 어떤 구성요소를 불필요하게 만들면 그 구성요소를 지웁니다.

관문과 루프#

킷의 동작은 서로 보완하는 두 생각으로 짜여 있습니다.

하네스 엔지니어링은 에이전트가 어디서, 무엇으로 행동하는지를 다룹니다. 세션 시작 시 주입하는 컨텍스트, 에이전트별로 고른 도구, 가드레일 훅, 디스크 위의 계획 파일이 여기에 속합니다.

루프 엔지니어링은 얼마나 오래, 얼마나 끈질기게 행동하는지를 다룹니다. 관문은 사람이 설계를 승인하는 의도적인 멈춤입니다(brainstorming, plan-task). 루프는 실행입니다. auto-dev는 승인된 계획을 매 단계 확인 없이, P0 질문·계획의 끝·가드에 닿을 때까지 밀고 갑니다. 루프는 관문을 우회하지 않습니다.

위치: rules/loop-engineering.md, skills/auto-dev/.

기획 프로토콜#

명세로 확인되지 않은 전제는 무엇보다 먼저 등급을 매깁니다.

“불확실하니 일단 멈춤"도 “사소하니 일단 진행"도 등급 판정을 건너뛴 것이라고 규칙에 적혀 있습니다. 계획은 완료 조건이 실행 가능한 명령일 때만 구현 단계로 넘어갑니다.

위치: rules/planning-protocol.md, skills/plan-task/.

완료의 정의#

“완료·끝·통과"는 판단이 아니라 명령의 출력입니다. 완료를 주장하기 전에 에이전트는 검증 명령을 새로 실행하고, 출력을 전부 읽고, 실패가 있으면 증거와 함께 실제 상태를 보고합니다. 그 전까지는 “구현 + 자체 검증 완료, 미결: …“이라고 말합니다.

종료 코드를 잃는 두 경우를 따로 짚습니다. 판정이 stdout 에만 찍히고 명령은 0으로 끝나는 경우, 그리고 파이프가 종료 코드를 삼키는 경우(gate | tail의 종료 코드는 tail의 것)입니다. 처방은 pipefail, 그리고 검증과 상태 변경(push·deploy 등)을 한 호출에 잇지 않는 것입니다.

auto-dev에서는 체크리스트 항목마다 계획에서 가져온 verify 명령이 붙고, checklist.json은 그 명령이 실제로 실행돼 0으로 끝났을 때만 항목을 통과로 바꿉니다.

위치: rules/definition-of-done.md, tools/checklist.py.

경계를 완료 조건으로#

계획이 모듈 경계를 정하거나 바꾸고, 프로젝트에 이미 경계 검사 도구(import-linter·Tach·dependency-cruiser·ESLint import 규칙·golangci-lint depguard)가 있으면, plan-task가 그 도구의 명령을 계획의 완료 조건에 넣습니다. 그러면 경계도 다른 모든 것과 같은 종료 코드 관문으로 지켜집니다. 킷이 도구를 대신 설치하지는 않습니다. 도구가 없으면 계획에 없다고 적고, 도입은 사용자가 정합니다. 검사를 통과시키려고 경계 설정을 느슨하게 하는 것은 수정이 아니라 멈춤 사유로 다룹니다.

위치: skills/plan-task/references/boundary-check.md.

적대적 리뷰#

코드를 쓴 에이전트는 그 코드를 잘 판단하지 못합니다. review-code는 완성된 diff를 분리된 컨텍스트에서 해커·머피의 법칙·미래의 나·까다로운 사용자, 네 페르소나로 읽고, REJECT·CONDITIONAL·ACCEPT 판정과 심각도별 결함을 냅니다. security-scan은 시크릿·인젝션·인증/인가·취약한 의존성을 봅니다. diff가 아니라 설계를 검토할 때는 multi-perspective-review가 최대 열 가지 관점으로 세 라운드를 돌고, devils-advocate가 결정 전에 실패 경로를 찾습니다.

위치: agents/dev/review-code.md, skills/multi-perspective-review/.

피드백 학습 루프#

리뷰·검증에서 나온 결함은 정규화돼 레포의 .git/kit/ 아래 피드백 원장에 기록됩니다. 원장에는 상한이 있고, 중복을 지우고, 오래된 항목은 감쇠합니다. 다음 세션이 시작될 때 반복되는 결함의 요약이 === LESSONS ===로 주입돼, 같은 실수를 저지르기 전에 잡습니다.

위치: rules/feedback-loop.md, tools/feedback_ledger.py.

규모에 맞는 오케스트레이션#

작은·중간 작업은 메인 세션에서 스킬이 주도하는 평평한 디스패치로 돕니다. 큰 계획에 한꺼번에 진행할 수 있는 독립 청크가 많으면, auto-dev가 청크 목록을 정리해 Claude Code 네이티브 동적 워크플로(ultracode)로 돌리라고 안내합니다. 메인 세션의 컨텍스트가 병목이 되지 않게 하려는 것입니다. 그 워크플로는 대화형이라 사용자가 직접 시작하고, 스킬이 대신 띄울 수는 없습니다.

전문 에이전트#

에이전트는 기획·개발·메타 역할로 나뉘고, 각자 frontmatter에 모델을 지정합니다. 기획 에이전트와 plan-implementation·review-code·devils-advocate는 Opus, 구현·수정·테스트·외부 조사·보안 스캔은 Sonnet, verify-code·git-workflow·analyze-dependencies·sync-docs처럼 가볍고 빠른 일은 Haiku를 씁니다. 파일을 고치는 에이전트(implement-code·fix-bugs·write-tests·sync-docs)는 격리된 git worktree에서 돌아 병렬 작업이 충돌하지 않고, 병합 복귀 규칙은 rules/parallel-worktree.md에 있습니다.

모델·effort 설정은 Claude Code 에서만 적용됩니다. Codex와 Antigravity는 에이전트를 서브에이전트로 노출하지 않고, 스킬이 같은 계약을 세션 안에서 수행합니다.

비신뢰 텍스트#

웹 결과·서드파티 문서·불러온 메모리·다른 세션의 로그는 지시가 아니라 데이터로 다룹니다. 인용으로 감싸고, 페이로드보다 먼저 방어 문구를 두고, 그 안의 지시는 따르지 않고 보고합니다. 그 텍스트가 저장되기 직전에 가장 중요합니다. 오염된 원장이나 메모리는 세션을 넘어 남기 때문입니다.

위치: rules/untrusted-text.md.