Skill 기반의 모듈형 Agentic Engineering 프레임워크 — 엔지니어링 규율과 AI 능력의 체계적 결합

Skill 기반의 모듈형 Agentic Engineering 프레임워크 — 엔지니어링 규율과 AI 능력을 체계적으로 결합하여, 요구사항 명확화(Requirement Clarification)부터 코드 리뷰(Code Review)에 이르는 전체 개발 프로세스를 커버하며, 피드백 루프를 통해 팀의 엔지니어링 경험을 자동으로 축적합니다.

Agentic Engineering 방법론에 대한 전체적인 추론 과정은 《제1원리로부터의 Agentic Engineering 사고》를 참조하십시오. 본 프레임워크는 해당 논문의 실전 적용 사례입니다.

git clone https://github.com/davidYichengWei/agentic-engineering-framework.git
cd agentic-engineering-framework

각 agent는 서로 다른 설정 디렉토리를 사용하므로, 세 개의 폴더를 해당 위치로 복사하십시오:

# Claude Code
cp -R agents skills commands ~/.claude/
# Codex CLI
...

agent와의 대화를 시작하고, 하나의 command를 시도해 보세요:

/code-review

Agent는 workflow-code-review skill을 로드하고 정의된 리뷰 프로세스에 따라 실행할 것입니다.

프레임워크는 문맥(Context)에 따라 자동으로 skill을 트리거하지만, command를 통해 능동적으로 호출하는 것이 더 신뢰할 수 있습니다. 전체 기능 개발 프로세스의 권장 순서는 다음과 같습니다:

/requirements-clarification → 요구사항 명확화, spec.md 생성 (AI가 가이드 역할 수행)
↓
/system-design → 설계안 설계, spec.md의 설계 섹션 작성 (AI가 협업자 역할 수행)
...

AI는 각 단계에서 서로 다른 역할을 수행합니다: 요구사항 단계에서는 가이드(Guide) (구조화된 질문을 통해 모호한 의도를 명시화하도록 도움), 설계 단계에서는 협업자(Collaborator) (트레이드오프 분석 및 대안 제시), 코딩 단계에서는 실행자(Executor) (명확한 사양에 따라 자율적으로 구현) 역할을 합니다. 각 단계에서 생성된 구조화된 문서는 자연스럽게 다음 단계의 고품질 문맥(Context)이 되어 선순환 구조를 형성합니다.

프로세스의 엄격함은 작업의 리스크에 비례합니다 — 매번 전체 프로세스를 거칠 필요는 없습니다:

작은 버그 수정? → 직접 /code-generation 호출
(복잡도를 평가하며, 간단한 변경은 spec 단계를 건너뛸 수 있습니다.)
운영 장애(Online Fault)? → 직접 /troubleshooting 호출
핫패스(Hot Path) 최적화? → 직접 /performance-optimization 호출
diff 리뷰? → 직접 /code-review 호출

AI agent는 세션 간 기억(Cross-session memory)이 없습니다 — 이번 대화에서 교정된 오류가 다음 대화에서 그대로 재현될 수 있습니다. Self-Refinement 메커니즘은 교정 경험을 지속 가능한 Skill로 변환함으로써 이 문제를 해결합니다.

두 가지 트리거 방식:

자동 트리거: 협업 중 AI의 오류를 교정하면, AI는 교정을 완료한 후 답변 끝에 가벼운 경험 축적 제안(3개 이내)을 제공하며, 사용자의 확인을 거쳐 실행됩니다.
수동 트리거 (/reflect): 현재 대화에 대한 전면적인 검토를 능동적으로 시작합니다. AI는 대화 중 교정된 모든 오류 패턴을 식별하고, 각 오류에 대해 완전한 진단 루프를 수행합니다: 오류 패턴 식별 → 근본 원인 진단 → 기존 지식 검색 → 제안 생성 → 사용자 확인 → 업데이트 실행.

전형적인 시나리오:

당신이 교정한 내용	축적되는 위치
"변수 명명은 snake_case를 사용해야 합니다"	std-* 코딩 규약 Skill
...

이를 통해 팀의 엔지니어링 경험은 수동으로 문서를 유지 관리하는 대신 대화 속에서 자연스럽게 성장할 수 있습니다. 매번의 교정은 프레임워크를 개선할 수 있는 기회입니다.

Best Practices와 Standards는 프레임워크에서 프로젝트별로 가장 맞춤화가 필요한 부분입니다. 프레임워크는 구체적인 내용을 규정하지 않습니다 — 대신 지식이 어떤 형태로 존재해야 하는지, 어떤 시점에 로드되어야 하는지, 어떻게 진화해야 하는지를 규정합니다.

새로운 std-* skill 생성:

skills/
└── std-python/
├── SKILL.md # 코딩 규약 개요
...

그 후 이를 필요로 하는 workflow skill에 등록합니다. 예를 들어 workflow-code-generation/SKILL.md의 「온디맨드 로드(On-demand loading)」 테이블에 다음을 추가합니다:

| std-pythonSkill | 파일이.py인 경우 |

새로운 bp-* skill 생성:

skills/
└── bp-security/
├── SKILL.md
...

그 후 해당하는 workflow skill에서 참조합니다. 일반적인 통합 지점은 다음과 같습니다:

통합 지점	추가 시점
workflow-code-generation → 단계 3 (규격 로드)	코딩 시 준수해야 할 규격
workflow-code-review/code-reviewer.md → 검토 차원	리뷰 시 확인해야 할 차원
workflow-test-generation → 테스트 전략	고려해야 할 테스트 카테고리
troubleshooting → 모듈 전용 가이드	특정 도메인의 트러블슈팅 지식

사례 파일을 troubleshooting skill의 reference 디렉토리에 넣습니다:

skills/
└── troubleshooting/
└── reference/
...

/skill-authoring을 사용하여 작성 가이드를 확인하세요. 핵심 원칙:

AI가 모르는 내용만 작성할 것 — 일반적인 지식이 아닌 프로젝트 특화 정보
SKILL.md는 500행을 넘지 말 것 — 상세 내용은 reference/ 파일에 배치
참조 깊이는 단 한 단계로 제한할 것 — A→B→C와 같은 연쇄 참조 금지

전체 작성 가이드는 skills/bp-skill-authoring/을 참조하세요.

AI 코딩 에이전트(Agent)는 능력이 매우 뛰어나지만, 규율(Discipline)이 부족합니다. 명확한 프로세스 제약이 없을 때 이들은 흔히 다음과 같은 문제를 일으킵니다:

• 요구사항 명확화 단계를 건너뛰고 바로 코드 작성 — 의도 변환 체인(Intent Transformation Chain)의 시작점에서 손실을 발생시키며, 이는 하류(Downstream)로 갈수록 더 큰 비용을 초래합니다.
• 대화 도중 코딩 규격을 망각 — LLM의 작업 기억(Working Memory)은 제한적이고 휘발성이 강하며, 대화가 길어짐에 따라 핵심 컨텍스트가 희석됩니다.
• 세션 간 출력 품질의 불일치 — LLM은 지속적인 기억(Persistent Memory)이 없으므로, 이전 세션에서 배운 교훈을 다음 세션에서 모두 잃어버립니다.
• 검토 속도를 훨씬 앞지르는 생성 속도 — 생성 비용은 급감하지만 검증 비용은 줄어들지 않아, 인지 과부하(Cognitive Overload)가 새로운 병목 현상이 됩니다.

본 프레임워크는 엔지니어링 베스트 프랙티스(Best Practices)를 에이전트가 읽을 수 있는 Skill 파일로 인코딩함으로써 이러한 문제들을 체계적으로 해결합니다:

핵심 프랙티스	해결 과제	프레임워크에서의 구현
Context Engineering (컨텍스트 엔지니어링)	컨텍스트의 품질이 출력 품질의 상한선을 결정함	Spec-First, 점진적 공개 (Progressive Disclosure), 온디맨드 로딩
AI 전 과정 참여	소스에서의 손실은 멀리 전파되며 복구 비용이 가장 높음	요구사항 명확화부터 코드 리뷰까지의 전체 워크플로우 (Workflow)
작은 작업 단위 추진 및 다층 검증	AI의 확률적 출력으로 인한 오류 누적 제어	작업 분해(Task Decomposition) + 단계별 리뷰 + 다차원 검증
Knowledge as Code (코드로 관리되는 지식)	팀의 고유 지식은 AI의 지식 공백 영역임	베스트 프랙티스 / 표준을 Skill로 인코딩
Error-Driven Refinement (오류 기반 개선)	LLM은 세션 간 기억이 없어 교정 경험이 유실되기 쉬움	Self-Refinement 자동/수동 피드백 루프

개인 개발자: Claude Code, Codex CLI, CodeBuddy, Cursor, Windsurf 등의 AI 코딩 에이전트를 사용하여 더 신뢰할 수 있고 구조화된 출력을 얻고자 하는 경우. 엔지니어링 팀: AI 에이전트가 팀의 코드베이스에서 작동하는 방식을 표준화하고자 하는 경우 — 시니어 엔지니어의 설계 원칙과 코딩 규격을 Skill로 인코딩하여 모든 팀원에게 배포함으로써 팀 내 역량 격차를 해소합니다. Skill 작성자: 성숙한 구조와 베스트 프랙티스를 기반으로 커스텀 에이전트 스킬을 작성하고자 하는 경우.

┌──────────────┐
│ 사용자 요청 │
└──────┬───────┘
...

프레임워크는 로딩 시점에 따라 세 가지 계층의 파일 구조로 나뉩니다:

agents/ → 서브에이전트(Subagent) 정의 (예: 코드 리뷰 시의 전용 reviewer)
commands/ → 사용자가 트리거하는 엔트리 포인트 (예: /code-generation, /troubleshooting)
skills/ → 상세 워크플로우 및 지식 정의 (온디맨드로 로드되어 상주 컨텍스트를 소모하지 않음)

에이전트는 독립적으로 하위 작업을 수행할 수 있는 전문 역할을 수행하며, 워크플로우 스킬(Workflow Skill)에 의해 필요에 따라 스케줄링됩니다.

Agent	역할
code-base-researcher
심층 코드베이스 탐색, 호출 체인(Call Chain) 추적, 모듈 의존성 분석
performance-reviewer
성능 전문 검토: 핫 패스(Hot Path), 메모리, 락 경합(Lock Contention), 알고리즘 복잡도
robustness-reviewer
견고성(Robustness) 전문 검토: 경계 조건(Boundary Conditions), 에러 처리, 리소스 누수
spec-compliance-reviewer
Spec 준수 여부 검토: 구현이 설계와 일치하는지 검증
standards-reviewer
코딩 표준 검토: 명명 규칙(Naming), 스타일, 매크로 사용, 락 프리미티브(Lock Primitives)
magical-prompt-reviewer
계약(Contract) 및 신뢰 체인 검토: 변경 사항으로 인한 계약 파괴 및 신뢰 체인 단절
review-critic
대립적 검증(Adversarial Verification): 후보 발견 사항(Finding)에 대한 반증을 찾아 오탐(False Positive) 기각

Command는 해당 Skill을 로드하는 바로가기입니다:

Command	로드되는 Skill
/requirements-clarification	workflow-requirements-clarification
/system-design	workflow-system-design
/code-generation	workflow-code-generation
/test-generation	workflow-test-generation
/code-review	workflow-code-review
/troubleshooting	troubleshooting
/performance-optimization	bp-performance-optimization
/reflect	self-refinement
/skill-authoring	bp-skill-authoring

Skill은 프레임워크의 핵심 운반체(Carrier)입니다. 즉, 모듈화되어 있고, 필요에 따라 로드되며, 조합 가능합니다. 프레임워크는 3단계 로딩 메커니즘을 채택하고 있기 때문에, 수많은 Skill이 있더라도 컨텍스트 윈도우(Context Window)를 압박하지 않습니다:

계층	내용	로드 시점	Token 비용
L1: Metadata	YAML frontmatter (name, description)	Agent 시작 시	~100/Skill
L2: Instructions	SKILL.md 본문 지침	Skill이 트리거될 때	< 5k
L3: Resources	reference/ (참조 문서), scripts/ (스크립트)	명시적으로 참조될 때	필요에 따라

Skill은 네 가지 유형으로 나뉩니다:

접두사	유형	역할	예시
workflow-*	워크플로우 (Workflow)	엔드 투 엔드(End-to-End) 프로세스 제어, 메인 엔트리	workflow-code-generation, workflow-code-review
bp-*	베스트 프랙티스 (Best Practice)	범용 엔지니어링 지식, 워크플로우에 의해 필요 시 로드	bp-coding-best-practices, bp-distributed-systems
std-*	코딩 표준 (Standard)	언어/팀별 특정 코딩 표준	std-cpp, std-go
(기타)	도구형 (Tool)	독립적인 능력	troubleshooting, self-refinement