이 레포가 무엇을 하는 물건인가.
아이디어를 판단 없이 시작했다가 중간에 가치 없음을 깨닫고, 경계 없는 요구로 코드가 산으로 가고, 검증 없이 "느낌상 돌아가니까" 납품하는 — 이 익숙한 실패들을 각각 막아서는 스킬을 단계마다 배치했습니다. 사용자는 명령을 외울 필요 없이 목표만 말하면, AI가 의도를 인식해 해당 스킬을 자동 발동합니다.
가장 독창적인 부분은 Frame(방안 교정) 단계의 3종 세트입니다. AI 어시스턴트마다 다른 "방안 편향"을 정조준합니다: geju (格局, 격국 — 판을 크게 보기)는 호환성·기존 코드에 겁먹고 소심한 패치만 내는 편향(주로 Codex)을 치료하고, goudi (苟帝 — 비전을 땅에 눌러 붙이기)는 방안을 너무 크고 붕 뜨게 잡는 편향(주로 Claude Code)을 치료하며, hai-razor (오컴의 면도날)는 필요를 자증 못 하는 개념(필드·상태·모듈·계층)을 잘라 과잉 복잡도를 치료합니다.
트렌딩 이유 · 경쟁 대비 장점.
스킬 팩 대부분이 "무엇을 시킬까"(작업 종류)의 모음인 데 비해, hai-stack은 "어떤 순서로 생각하게 할까"(의사결정 체인)의 모음입니다. 특히 "AI별 편향을 식별하고 반대 방향 스킬로 헷지한다"는 발상 — Codex엔 격국을, Claude엔 압축을 — 은 멀티 에이전트 시대의 실전 지혜로 화제가 됐습니다.
| 비교 항목 | 일반 스킬 팩 | hai-stack |
|---|---|---|
| 구성 원리 | 작업 종류별 (코드리뷰·테스트…) | 의사결정 단계별 (판단→정의→검증) |
| AI 편향 대응 | 없음 | geju(소심함)·goudi(붕 뜸)·razor(과잉) 3방향 헷지 |
| 결론 형식 | 자유 서술 | 스코어카드·kill-list·Go/No-Go 등 구조화 산출물 |
| 언어 | 영어 단일 多 | 영·중 이중 (zh_CN 병행 유지) |
가치 판단 없이 모든 아이디어가 실행에 들어가고, PRD 없는 요구는 코드를 쓰면서 계속 흔들리며, 테스트는 구현 후 "보충"되어 자기 위안이 됩니다.
hai-idea는 아이디어에 做/先验证/重塑/延后/砍掉(실행/검증먼저/재구성/연기/폐기) 5단 판정과 점수표를 내고, hai-goal은 착수 전 검증 가능한 목표·단계·증명(proof)·중단 기준을 문서로 강제합니다. 체인은 강제 절차가 아니라 "언제든 쓸 수 있는 판단 지점들"로 설계됐습니다.
순수 마크다운 스킬 팩 — 구조가 곧 기술.
| 레이어 | 구성 | 역할 |
|---|---|---|
| 판단·프레이밍 | hai-idea · geju · goudi · hai-razor | 가치 판정 / 격국 열기 / 땅에 붙이기 / 군더더기 자르기. |
| 정의·계획 | hai-prd · hai-goal · entity-model-auditor | PRD 필요성·경계·검수 / 목표 문서 / PRD↔데이터모델 필드 대조. |
| 아키텍처·품질 | hai-architecture · hai-tdd · clean-code-reviewer · hai-ast-grep | Ousterhout(APoSD) 기반 아키텍처 리뷰 / 테스트 선행 / 클린코드 / ast-grep 린트 규칙 제작. |
| 문서 감사 | hai-audit-docs-internally / -against-code | 문서 내부 일관성 / 문서↔코드 일치 검사. |
| 리포트 | hai-visual-report · create-visual-card | 판단 결과를 HTML 리포트·공유용 카드로 (스크린샷 스크립트 동반). |
| 형식 | SKILL.md + references/ + agents/openai.yaml | 스킬 본체 + 출력 템플릿·패턴 부록 + Codex 에이전트 선언 — 멀티 CLI 호환. |
아이디어 하나가 체인을 타고 납품까지.
스킬 하나의 내부 구조도 일관됩니다: SKILL.md(절차·판단 기준) + references/output-template.md(결론의 고정 양식) + 필요시 anti-patterns.md(하지 말 것)·worked-example.md(완성 예시). 출력 양식을 템플릿으로 박아두는 것이 핵심인데 — AI의 결론이 매번 다른 모양이면 비교·축적이 안 되기 때문입니다. geju가 내는 "보수 vs 클린 vs 단계적" 3옵션과 kill-list, goudi가 내는 "성공/실패 신호 + 손절 규칙" 같은 산출물이 모두 정형화돼 있습니다.
병원의 진료 프로토콜과 같습니다. 환자(아이디어)가 오면 바로 수술(코딩)하지 않고 — 분류(idea) → 검사(frame) → 진단서(PRD) → 수술 계획(goal) → 집도(TDD) → 경과 기록 대조(audit) 순서를 밟습니다. 각 단계의 기록 양식이 정해져 있어 누가 봐도 판단 근거를 추적할 수 있죠.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
skills/geju/ · goudi/ | 이 팩의 발명품 — 편향 교정 스킬의 원형. 이름도 철학도 중국어 그대로. |
hai-architecture/references/ | go/ts 패턴·red-flags·완성 예제까지 — 스킬 하나가 작은 교과서. |
*/references/output-template.md | 모든 스킬이 출력 양식 고정 — 결론의 비교 가능성 확보 장치. |
*/agents/openai.yaml | Claude 스킬이면서 Codex 에이전트로도 선언 — 이중 생태계 배포. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
"프로세스 문서"는 안 읽히지만 "의도 인식 시 자동 발동하는 스킬"은 강제력이 있습니다. 팀의 작업 방식을 AI 시대에 이식하는 형식으로서 이 레포 구조 자체가 견본입니다.
"Codex는 호환성·역사적 부채를 과대평가해 패치식으로 움츠러들고, Claude는 비전이 크지만 첫걸음이 무르다" — 실사용에서 추출된 이 관찰만으로도 멀티 CLI 운용에 즉시 유용합니다.
판단을 "글"이 아니라 "양식"으로 받으면 축적·비교·재사용이 됩니다. output-template들을 모아 읽으면 구조화 산출물 설계의 패턴북이 됩니다.
코드 패턴을 구조적으로 검색·치환하는 ast-grep의 규칙을 AI가 짜게 하는 스킬 — 코드베이스 일괄 정리·마이그레이션 자동화에 바로 응용 가능합니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 실행 환경 | 스킬을 지원하는 AI 코딩 어시스턴트 — Claude Code·Codex(openai.yaml 동봉) 등. |
| 설치 | skills/를 어시스턴트의 스킬 디렉토리에 복사 (Makefile 참조). |
| 언어 | README·스킬 본문이 중국어 중심(영문판 병행) — 번역 도구와 함께 읽으면 무리 없음. |
| 부가 도구 | create-visual-card는 스크린샷용 Node 스크립트, ast-grep 스킬은 ast-grep 설치 필요. |
난이도별로 손에 익히는 단계.
묵혀둔 사이드 프로젝트 아이디어 5개를 hai-idea에 넣어 스코어카드와 5단 판정을 받아 봅니다. "다 하고 싶었는데 사실 砍掉(폐기)가 셋"이라는 경험이 이 팩의 가치를 가장 빨리 보여줍니다.
같은 리팩토링 과제를 geju(판 키우기)와 goudi(눌러 붙이기)로 각각 돌려 산출물을 비교합니다 — 하나의 문제에 대한 두 극단의 교정이 어떻게 다른 결론을 내는지.
이번 주 실제 작업 하나를 hai-goal에 넣어 "proof 딸린 todo + Go/No-Go + 중단 규칙" 문서를 받고, 그대로 실행하며 문서가 실제로 흔들림을 줄이는지 검증합니다.
내가 쓰는 AI의 반복 편향(예: 과잉 방어 코드, 장황한 문서)을 관찰·기록하고, geju/goudi의 구조(thesis·kill-list·옵션 3개·검증 경로)를 본떠 교정 스킬을 만들어 봅니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 체인 전체 훑기 + hai-idea 체험 | README · 실습 1 |
| 2주차 | 편향 교정 3종 정독 | geju·goudi·hai-razor SKILL.md |
| 3주차 | APoSD 원전과 hai-architecture 대조 | 『A Philosophy of Software Design』 |
| 4주차 | PRD·goal 문서 작법 실전 | hai-prd·hai-goal · 실습 3 |
| 5주차 | 내 방법론의 스킬화 | 실습 4 · output-template 모음 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| geju (格局) | "판을 크게 보기" — 소심한 패치식 방안을 고위 목표 모델로 끌어올리는 스킬. |
| goudi (苟帝) | "끈질기게 버티는 황제" 뉘앙스 — 거창한 방안을 최소 검증 가능한 첫걸음으로 압축. |
| hai-razor | 오컴의 면도날 — 필요를 자증 못 하는 개념을 보류/병합/삭제/연기로 판정. |
| kill-list | 삭제·병합·분리해야 할 항목 목록 — geju 산출물의 핵심. |
| Go/No-Go | 진행/중단을 가르는 명시적 판단 기준. |
| proof 딸린 todo | 완료 증명 방법이 함께 정의된 할 일 — "느낌상 완료"를 차단. |
| PRD | 제품 요구 문서 — hai-prd는 작성 여부 판단부터 다룸. |
| APoSD | Ousterhout의 설계 철학 — 복잡도·모듈 깊이·정보 은닉 중심 리뷰 렌즈. |
| ast-grep | 구문 트리 기반 코드 검색·치환 도구 — 린트 규칙을 스킬로 제작. |
| output-template | 스킬 결론의 고정 양식 — 판단의 축적·비교를 가능케 하는 장치. |