작동 원리 심층 해부
이 프로젝트가 어떻게 AI의 행동을 근본적으로 교정하는지 그 내부 아키텍처와 원리를 깊이 파헤쳐 보겠습니다. 가장 중요한 개념은 소프트웨어 개발 생명주기를 강제하는 파이프라인과 그 파이프라인을 구동하는 마크다운 문서의 치밀한 구조입니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
flowchart LR
A["요구사항 명세 설계"]
B["세부 작업 계획 수립"]
C["점진적 기능 구현"]
D["엄격한 테스트 검증"]
E["다각도 코드 리뷰"]
F["안전한 운영 배포"]
A --> B
B --> C
C --> D
D --> E
E --> F
위 다이어그램처럼 개발의 모든 단계를 명시적으로 나누고, 각 단계마다 슬래시 명령어를 통해 AI의 작업 컨텍스트를 통제합니다.
7가지 주요 슬래시 명령어
agent-skills는 크게 7가지의 진입점 명령어를 제공합니다. 각 명령어는 AI가 현재 어떤 맥락에서 어떤 목표를 달성해야 하는지 명확히 규정합니다.
- /spec: 코드를 짜기 전에 요구사항을 묻고 인터페이스를 명확히 정의합니다. 사용자의 모호한 아이디어를 구체적인 기획서 수준으로 끌어올립니다.
- /plan: 거대한 작업을 검증 가능한 가장 작은 단위로 쪼개어 계획 문서를 작성합니다.
- /build: 한 번에 하나씩, 철저하게 범위를 제한하여 코드를 점진적으로 작성합니다. 파일 하나를 수정할 때마다 계획서와 대조합니다.
- /test: 구현된 코드가 올바르게 작동한다는 물리적 증거를 요구합니다. 유효한 테스트 코드가 통과해야만 다음 단계로 넘어갈 수 있습니다.
- /review: 머지하기 전 보안, 성능, 유지보수성 등 다각도에서 코드를 꼼꼼히 점검합니다.
- /webperf: 웹 애플리케이션의 성능을 측정하고, 무분별한 최적화 대신 실제 병목 구간을 찾아 개선합니다.
- /code-simplify: 똑똑해 보이지만 읽기 어려운 복잡한 코드보다, 지루할 정도로 직관적이고 명확한 코드를 지향하도록 코드를 정리합니다.
- /ship: 최종적으로 안전하게 운영 환경으로 내보낼 준비를 마칩니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
sequenceDiagram
participant Dev as 개발자
participant Agent as AI 에이전트
participant Skill as Agent Skills 지침
Dev->>Agent: 새로운 결제 모듈 만들어줘 명령어 호출
Agent->>Skill: 결제 기능 구현 관련 규칙 및 제약사항 조회
Skill-->>Agent: 테스트 주도 개발 강제 지침 반환
Agent->>Agent: 실패하는 테스트 케이스 우선 작성
Agent->>Dev: 작성된 테스트 코드 검토 및 승인 요청
Dev->>Agent: 테스트 코드 승인 완료
Agent->>Agent: 실제 비즈니스 로직 구현 및 테스트 통과 확인
Agent-->>Dev: 작업 완료 보고 및 추가 코드 리뷰 대기
마크다운 스킬 문서의 데이터 모델 구조
단순한 텍스트 파일이 어떻게 AI의 자유분방한 행동을 통제할 수 있을까요? 애디 오스마니는 각 마크다운 파일을 정교한 데이터베이스 스키마처럼 체계적으로 설계했습니다.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#F0EEE9","primaryBorderColor":"#2a78d6","primaryTextColor":"#2b2926","secondaryColor":"#e8f0fb","secondaryBorderColor":"#4a3aa7","secondaryTextColor":"#2b2926","tertiaryColor":"#eafaf3","tertiaryBorderColor":"#1baf7a","tertiaryTextColor":"#2b2926","lineColor":"#8a8578","textColor":"#2b2926","edgeLabelBackground":"#F0EEE9","noteBkgColor":"#F0EEE9","noteTextColor":"#2b2926","noteBorderColor":"#8a8578","clusterBkg":"#faf9f6","clusterBorder":"#d8d4c8","fontFamily":"Pretendard, sans-serif"}}}%%
erDiagram
SKILL_DOC_OBJ {
string skillName
string coreDescription
}
CHECKPOINT_LIST_OBJ {
string validationCondition
boolean mandatoryFlag
}
ANTI_EXCUSE_TABLE_OBJ {
string anticipatedAiThought
string enforcedAction
}
SKILL_DOC_OBJ ||--o{ CHECKPOINT_LIST_OBJ : "검증조건포함"
SKILL_DOC_OBJ ||--o{ ANTI_EXCUSE_TABLE_OBJ : "합리화차단장치포함"
여기서 가장 독창적이고 빛나는 부분은 바로 안티 합리화 테이블입니다. AI가 핑계를 대려는 순간을 미리 예측하고 원천적으로 차단합니다. 스킬 문서 내부에는 다음과 같은 지침이 명시적인 표 형태로 존재합니다.
- AI의 예상되는 생각: 이 변경사항은 너무 작고 단순해서 굳이 테스트를 작성할 필요가 없다.
- 강제된 행동 지침: 크기와 상관없이 반드시 테스트를 작성한다. 가장 사소해 보이는 한 줄의 변경이 프로덕션 환경에서 대형 장애를 일으키는 법이다.
이러한 강력한 안전 장치 덕분에 AI는 스스로 타협하려는 성향을 억누르고, 지루하지만 필수적인 프로세스를 끝까지 완수하게 됩니다.