AI 네이티브 개발 흐름과 HandStack 스킬
이 문서는 전체 그림을 한 장으로 보여 줍니다. 처음이라면 여기서 흐름을 이해한 뒤 자기 역할의 문서(개발자 01, 운영자 02, 업무 담당자 03)로 넘어가세요.
핵심 아이디어 세 가지
- 코드 작성이 병목이 아니다. AI가 코드를 빨리 쓰면 병목은 앞(무엇을 만들지 정하기)과 뒤(검토·테스트·배포)로 옮겨 갑니다. 그래서 스킬은 구현만이 아니라 규칙 정리, 연결 점검, 검증, 배포까지 다룹니다.
- 단계마다 산출물을 파일로 남긴다. 의도(
intent.md) → 명세(spec.md) → 계획(plan.md) → 코드와 테스트 → 검토가 붙은 변경 요청(PR) → 릴리즈 기록. 다음 단계는 앞 단계 파일을 읽고 시작하므로, 사람과 AI 모두 "왜 이렇게 만들었는지"를 추적할 수 있습니다. - 판단은 사람이, 반복은 도구가. 반드시 지켜야 하는 것은 스킬(권고)에 더해 점검 스크립트와 훅(강제) 으로 막습니다. AI는 운영 반영 직전까지 준비하고, 운영 반영은 사람이 승인합니다.
한 사이클의 흐름
| 단계 | 하는 일 | 산출물 | 주 담당 | 쓰는 스킬·도구 | 사람의 관문 |
|---|---|---|---|---|---|
| 1 계획 | 문제와 원하는 결과를 자기 말로 기록 | intent.md | 업무 담당자 | (스킬 없이 AI와 대화) 템플릿 | 업무 책임자가 채택/보류 |
| 2 설계 | 규칙·화면 상태·권한·서비스 초안을 명세로 | spec.md, 규칙 표 | 업무 담당자 + 개발자 | handstack-rules-and-verification, handstack-screen-development(UX 상태) | 담당자가 "내가 원한 것"을 확인, 충돌·우려 해소 |
| 3 구현 | 계획 모드로 계획을 먼저 만들고, 안쪽부터 구현 | plan.md, 코드 | 개발자 | handstack-feature-delivery → 화면/거래/함수/외부/프롬프트/워크플로 스킬 | 개발자가 계획 승인 |
| 4 테스트 | 연결 점검, 규칙 테스트, 동시성·권한 | 점검 결과, 테스트 표 | 개발자 | handstack-source-trace, design_lint.py, handstack-rules-and-verification | "완료" 전에 출력 첨부 |
| 5 배포 | 검토, 빌드, 격리 스모크, 승인, 반영 | PR, 릴리즈 기록 | 개발자 + 운영자 | handstack-cicd-pipeline, handstack-host-operations | 운영 반영 승인(릴리즈 관리자) |
| 6 유지보수 | 신호 감시, 장애 진단, 새 의도로 되돌리기 | 장애 기록, 새 intent.md | 운영자 | handstack-troubleshooting, handstack-host-operations | 즉시 수정/예약/기각 결정 |
6단계의 결과가 다시 1단계의 intent.md가 되어 순환합니다.
스킬 지도 (어떤 일에 어떤 스킬?)
| 하고 싶은 일 | 스킬 |
|---|---|
| 새 화면·기능을 처음부터 끝까지 | handstack-feature-delivery (전체 순서를 안내하고 아래 스킬을 부른다) |
| 화면 HTML/JS, 바인딩, 그리드, 팝업 | handstack-screen-development |
거래(.txn)와 SQL(.dbc) | handstack-transaction-contracts |
서버 함수(.fnc) | handstack-function-contracts |
| 외부 API 호출, 그래프 DB, 파일 첨부 | handstack-external-contracts |
AI 프롬프트·판단 계약(.pmt) | handstack-prompt-contracts |
| 여러 서버 호출을 한 번에 엮기 | handstack-workflow-contracts |
| 업무 규칙, 동시성, 테스트 케이스 | handstack-rules-and-verification |
| 메뉴 등록, 모듈 구조, C# 모듈 | handstack-module-development |
| 화면 → SQL 호출 경로를 읽고 싶다 | handstack-source-trace |
| 오류 메시지·증상의 원인 | handstack-troubleshooting |
| 서버 실행·설정·CLI | handstack-host-operations |
| 빌드·배포 파이프라인, 롤백 | handstack-cicd-pipeline |
| IDE 도구 자체 개발 | handstack-ide-development |
처음에는 handstack-feature-delivery(만들기), handstack-source-trace(읽기), handstack-troubleshooting(고치기) 세 개만 기억해도 됩니다.
참여자별 한 줄 요약
- 업무 담당자: 원하는 일을
intent.md로 쓰고, 규칙·화면 상태·인수 시나리오를 확정하고, 결과를 시나리오로 확인합니다. → 03 - 개발자: 명세를 계획으로 바꾸고, 스킬을 따라 구현하고, 점검 출력을 붙여 검토를 요청합니다. → 01
- 운영자: 환경을 알고, 배포 방식을 하나로 정하고, 승인 관문과 롤백을 지키고, 신호를 의도로 되돌립니다. → 02
어디서부터 도입할까 (순서 제안)
한꺼번에 하지 않아도 됩니다. 앞 단계가 뒤 단계의 전제는 아니므로 필요한 곳부터 시작하세요.
| 시기 | 할 일 | 효과 |
|---|---|---|
| 첫날 | 스킬 설치, 프로젝트 AGENTS.md/CLAUDE.md 작성(템플릿), 기존 화면 하나를 handstack-source-trace로 읽어 보기 | 코드베이스 이해가 빨라지고 AI가 프로젝트 규칙을 안다 |
| 첫 주 | 작은 기능 하나를 plan.md → 구현 → 점검 출력 첨부로 진행 | 연결 불일치를 구현 중에 발견 |
| 첫 달 | 규칙 표·결정표, 변경 범위 점검을 CI에 연결, 보호 경로 훅 | 같은 실수 반복 감소, 검토 시간 단축 |
| 분기 | 배포 관문 훅, 릴리즈 기록, 롤백 리허설, 신호 → intent.md 순환 | 안전하게 속도를 높임 |
효과를 재는 간단한 지표 (제안)
숫자는 팀 상황에 맞게 정하세요. 아래는 추적하기 쉬운 것들입니다.
- 처음 구현한 변경이 재작업 없이 병합되는 비율 (PR 이력)
hs_inspect.py가 구현 중에 잡은 불일치 수 vs. 검토·테스트·운영에서 발견된 불일치 수- 같은 지적이 두 번 나온 횟수 (두 번째부터는
AGENTS.md/REVIEW.md에 한 줄 추가) - 배포 후 롤백 비율, 배포 후 확인 실패 비율 (릴리즈 기록)
intent.md가 만들어진 뒤spec.md확정까지 걸린 시간
이 가이드와 스킬의 한계
- 스킬은 권고입니다. 반드시 지켜야 하는 규칙은 점검 스크립트, 훅, CI 게이트로 강제하세요(훅 템플릿).
- 스킬은 소스 대조와 정적 점검으로 만들었습니다. 사용하는 HandStack 버전과 프로젝트 규약이 다르면 프로젝트 문서가 우선합니다.
- 점검기(
hs_inspect.py등)는 정규식 기반이라 후보를 알려 줄 뿐입니다. 실행(거래 호출, 브라우저, DB)으로 확인한 것과 아닌 것을 보고서에서 구분하세요. - AI가 만든 산출물의 책임은 승인한 사람에게 있습니다.