hGATE가 AI 코딩을 명세부터 배포까지 추적한다

hGATE는 AI 코딩 에이전트를 활용한 명세 기반 개발 워크플로다. 사람이 요구사항과 경계를 확인하고 각 단계의 진행을 승인하며, 명세부터 생성된 코드와 테스트, 배포된 변경 사항까지 추적하도록 설계됐다.

GitHub에서 보기 · 빠른 시작 안내

hGATE는 마크다운 스킬 8개, 결정론적 검증 도구, 세션 시작 시 동기화하는 프로토콜로 구성되며 MIT 라이선스로 제공된다.

작동 방식

에이전트는 한 번에 전문 스킬 하나를 추천하고 실행한다. 요구사항과 경계, 계획, 워크플로 전환은 사람이 확인한다. 세 가지 원칙을 전체 과정에 적용한다.

• 코드보다 명세 우선: 각 단계는 즉석에서 만든 프롬프트가 아니라 승인된 명세에 연결된다. 합의한 내용보다 앞서 코드 생성을 진행하지 않는다.
• 도메인 경계 유지: 동작을 작성하기 전에 바운디드 컨텍스트(BC)를 정한다. 검토 단계에서는 생성된 코드가 승인된 명세 밖의 동작을 구현하지 않았는지 확인한다.
• 처음부터 끝까지 추적: 명세, 결정, 테스트, 배포된 코드가 각 단계의 기록으로 남는다. 다음 작업을 시작하기 전에 세션 시작 프로토콜이 기록을 대조한다.

hgate-guide는 프로젝트 산출물을 살펴보고 다음에 할 스킬 하나를 추천한다. 이 스킬이 추천된 작업을 자동으로 시작하거나 생명주기 상태를 바꾸지는 않는다.

각 BC의 첫 명세는 지금 배포할 범위를 다루면 된다. 완전하고 영구적인 명세를 처음부터 만들 필요는 없다. 이후 bc-enhancement를 통해 이해가 쌓이는 대로 기능을 더하고, 대부분의 BC는 여러 차례 개선 과정을 거친다.

일반적인 흐름은 도메인 탐색, BC 명세 정리, BC 검토, BC 구현, BC 검토, 여러 BC에 걸친 검증으로 이어진다. 이미 배포한 BC에 새 기능을 더하거나 기존 동작을 바꿀 때는 bc-enhancement로 반복 작업을 한다. 이는 버그 수정에만 쓰는 예외 경로가 아니며, 매번 전체 BC 검토로 마무리한다.

기존 코드베이스에서 시작한다면 domain-exploration과 bc-refinement가 코드와 API, 스키마를 근거로 삼아 첫 명세 초안을 만들 수 있다. 이어 bc-review full을 실행해 명세와 코드 사이에 이미 생긴 차이를 드러낸다. 도메인 경계를 이미 알고 있다면 architecture-decision-exploration으로 도메인 매핑을 반복하지 않고 시스템 간 기술 결정을 다룰 수 있다.

산출물과 검증

hGATE는 관례만 제시하는 대신 확인할 수 있는 산출물을 남기는 데 초점을 둔다. 제작자가 설명한 주요 기능은 다음과 같다.

• 중요한 기술·도메인 결정은 선택된 결정뿐 아니라 맥락과 검토한 대안, 결과를 담은 아키텍처 결정 기록(ADR)으로 남긴다.
• 검토 단계는 승인된 명세의 항목에 연결되지 않는 동작을 생성 코드가 구현했는지 표시한다.
• 각 행동 주도 개발(BDD) 시나리오는 실제 테스트와 연결된다. 결정론적 검증 도구인 verify:bdd는 시나리오 ID와 Jest 테스트를 대조하며, BDD에서 테스트 주도 개발(TDD)로 넘어가는 과정의 사람 승인도 기록한다. 내장 Gherkin 뷰어로 BC의 시나리오를 볼 수도 있다.
• 이름 변경이나 성능 조정처럼 명세에 영향을 주지 않는 변경은 보수적인 기준에 따라 전체 파이프라인을 건너뛸 수 있다. 이 빠른 경로도 감사 기록은 남긴다.
• 결정과 생명주기 상태는 전역 파일 하나가 아니라 해당 BC 옆에 저장한다.
• 각 BC의 통합 지점에는 명시적인 부패 방지 계층(ACL)을 둬 외부 시스템의 모델이 내부 모델에 섞이지 않도록 한다.
• 속성 기반 테스트는 예시뿐 아니라 항상 성립해야 하는 비즈니스 규칙을 생성된 수천 개 사례에서 확인할 수 있다. 위험에 따라 선택적으로 추가한다.
• 사람은 동작 예시와 비즈니스 규칙을 각각 검토하고 승인한다. 각 승인은 영구 기록으로 남으며, 테스트 통과가 사람의 판단을 대체하지 않는다.
• 명세의 일관성을 자동으로 확인하고 문제가 있는 파일과 줄을 보고한다.
• 뷰어가 사용하는 프로젝트 개요는 명세에서 생성해 수동 편집이나 오래된 정보에 의존하지 않도록 한다. CI는 개요가 최신 상태에서 벗어났는지 알린다.

스킬과 적용 방식

8개 스킬은 각각 확인 가능한 산출물을 만든다. 스킬은 단계별로 나뉘며, 필요한 참고 자료를 요청할 때 불러와 에이전트가 다루는 문맥을 작게 유지한다.

스타트업은 문서를 간소화하고 공식 승인 회의를 생략할 수 있지만, 세션 시작 동기화는 필수로 유지한다. BC 검토는 병합을 계속 통제하며, 폐기할 프로토타입 코드에는 가벼운 산출물을 사용할 수 있다.

스케일업은 모든 스킬을 예정된 의식 없이 비동기적으로 활용한다. 명세는 코드 옆 저장소에 두고, 검토 관문은 회의 대신 풀 리퀘스트에서 실행하며, 결정과 상태 기록은 BC별로 관리한다.

엔터프라이즈는 추적성을 편의가 아닌 규정 준수 산출물로 다룬다. 생명주기 전환 전 독립 검토가 필요하고, 결정과 상태 기록을 정기적으로 감사하며, 시나리오와 테스트의 연결을 가정하지 않고 확인한다.

빠른 시작

저장소에서 스킬과 검증 도구를 프로젝트로 복사하고 세션 시작 프로토콜을 설치한 뒤 AI 에이전트에 안내 스킬을 요청한다.

1. 프로젝트에 hGATE를 추가한다.

mkdir -p /path/to/your-project/.github/skills
cp -R skills/* /path/to/your-project/.github/skills/
mkdir -p /path/to/your-project/tools
cp -R tools/. /path/to/your-project/tools/
# copies every tool plus project-schema.json and other shared artifacts
# preserve each skill's SKILL.md, assets/, references/, decisions.md
# optional Goal 3: install fast-check for tools/business-verification

2. 프로젝트 지침을 설치한다.

cp templates/CLAUDE.hgate.md /path/to/your-project/CLAUDE.md
# already have a CLAUDE.md? append the template, keep your conventions

3. 에이전트와 함께 hgate-guide를 시작한다.

I want to start using hGATE for this project.