GitHub 레퍼런스를 활용한 에이전트 설계와 개선 방법3 : 비전공 초보 개발자를 위한 AI 에이전트 설계의 4가지 원리
2026.08.11
이번에는 Superpowers·GSD·GBrain·Gptaku를 단순한 “개발자용 도구”가 아니라, AI가 더 안정적으로 일하도록 돕는 교육 설계 사례로 읽어 보았습니다. 결론부터 말하면, 비전공 초보 개발자에게 필요한 것은 프레임워크를 한꺼번에 설치하는 일이 아니라, AI가 일하는 절차·기억·지식·도움말을 단계적으로 설계하는 일입니다.
1. 시도하고자 했던 것과 그 이유
지난 사례글에서는 GitHub 오픈소스를 벤치마킹하고, 내 목적에 맞게 구조와 원리를 가져오는 일을 ‘전이’ 관점으로 정리했습니다. 이번 사례글에서는 그 관점을 실제 네 개의 GitHub 레퍼런스에 적용했습니다.
Superpowers: AI가 설계·계획·테스트·리뷰의 개발 절차를 지키도록 돕는 스킬 프레임워크
GSD Core: 긴 작업에서 AI가 앞선 결정과 요구사항을 잊지 않도록 컨텍스트와 명세를 관리하는 프레임워크
GBrain: 문서와 기록을 축적하고, 검색을 넘어 맥락 있는 답을 합성하도록 돕는 지식 브레인
Gptaku Plugins: Claude Code 사용자가 Git, 문서화, 리서치, PRD 등에서 막히는 지점을 플러그인 단위로 지원하는 마켓플레이스
비전공 초보 개발자는 AI 코딩 도구를 처음 접할 때 두 가지 어려움을 겪기 쉽습니다. 첫째, AI가 처음에는 똑똑해 보이지만 작업이 길어질수록 앞의 요구사항을 잊거나 결과가 산만해집니다. 둘째, 도구와 용어가 너무 많아 무엇부터 설치하고 배워야 할지 막막해집니다.
그래서 이번 시도의 목적은 “어떤 프레임워크가 최고인가?”를 고르는 것이 아니었습니다. 대신 AI가 잘 일하지 못하는 원인을 네 가지로 나누고, 초보자가 자기 문제에 맞는 설계 원리를 선택하도록 돕는 것이 목표였습니다.
제가 보기에 이 네 프로젝트는 결국 같은 질문으로 만납니다.
“AI에게 더 많은 일을 시키려면, AI에게 어떤 제약과 안내를 제공해야 하는가?”
이 질문은 코딩에만 국한되지 않습니다. 교육 콘텐츠, 행정 문서, 강의안, 컨설팅 보고서처럼 긴 맥락과 반복 검토가 필요한 모든 작업에도 적용됩니다. 첨부 자료에서 제시한 해석처럼, 이는 AI를 하나의 ‘학습자’로 보고 절차와 환경을 설계하는 LLM용 교수설계로 볼 수 있습니다.
2. 진행 방법
이번 정리는 도구의 기능을 나열하는 대신, 각각이 해결하는 실패 문제와 교육공학적 원리를 연결하는 방식으로 진행했습니다.
1) 네 가지 실패 문제로 분류
먼저 AI 에이전트가 실패하는 상황을 네 가지로 나눴습니다.
초보자가 겪는 문제 | 참고한 프레임워크 | 전이할 핵심 원리 |
|---|---|---|
AI가 설계 없이 코드를 먼저 만들거나 검증을 빼먹는다 | Superpowers | 절차를 먼저 설계한다 |
긴 작업에서 AI가 앞의 결정을 잊는다 | GSD Core | 상태와 맥락을 별도 문서로 관리한다 |
자료는 많은데 필요한 답을 바로 얻지 못한다 | GBrain | 지식을 축적하고 관계를 연결한다 |
Git·PRD·리서치 같은 특정 단계에서 반복적으로 막힌다 | Gptaku Plugins | 막힘을 작은 스킬·플러그인으로 분해한다 |
Superpowers는 브레인스토밍, 격리된 작업공간, 세부 계획, 서브에이전트 실행, TDD, 코드 리뷰, 브랜치 마무리라는 기본 워크플로우를 제시합니다. 특히 테스트를 먼저 작성하는 RED–GREEN–REFACTOR 흐름을 포함해, AI가 ‘일단 코드부터 쓰는’ 습관을 제어합니다.
GSD Core는 컨텍스트 엔지니어링과 명세 기반 개발에 초점을 둡니다. 문서상으로도 Discuss → Plan → Execute → Verify 단계 루프와 컨텍스트가 오래 쌓일수록 품질이 흔들리는 문제를 다룹니다.
GBrain은 지식을 일반 Git 저장소의 Markdown 파일로 저장하고, 수집·정제·질의·인용 보정·일정 관리 등을 위한 여러 스킬을 제공합니다. 또한 수집기에서 신호를 받고, 에이전트가 분석한 뒤, 브레인 페이지를 생성·갱신하고, 검색 가능한 형태로 인덱싱하는 흐름을 제시합니다.
Gptaku Plugins는 Claude Code 환경에서 사용할 수 있는 플러그인 모음으로, 처음 마켓플레이스를 등록한 뒤 필요한 플러그인을 선택 설치하는 방식을 제공합니다. 초보자에게는 모든 기능을 한꺼번에 배우게 하기보다, 문제별 도구를 단계적으로 제공한다는 점에서 의미가 있습니다.
2) 교육공학 언어로 번역
다음으로 개발 프레임워크를 비전공자가 이해할 수 있는 교육공학 언어로 번역했습니다.
Superpowers는 스캐폴딩입니다. 초보 학습자에게 “잘해 보세요”라고 말하는 대신, 해야 할 순서와 검증 기준을 제공하는 것처럼 AI에게도 작업 절차를 제공합니다. 외재적 인지부하를 줄이는 방식입니다.
GSD는 작업 기억 보조장치입니다. 사람도 긴 회의와 복잡한 프로젝트에서 회의록·체크리스트·결정 기록이 없으면 맥락을 잃습니다. GSD의 명세와 상태 관리 역시 AI의 긴 작업을 작은 단위로 나누고, 다음 작업에 필요한 기억을 외부 문서에 남기는 접근입니다.
GBrain은 개인 지식관리 시스템입니다. 단순히 파일을 저장하는 것이 아니라, 기록을 다음 질문에서 다시 활용할 수 있게 구조화합니다. 따라서 ‘검색창’보다 ‘축적되는 업무 기억’에 가깝습니다.
Gptaku는 적시학습 도구 상자입니다. 초보자가 처음부터 Git, PRD, 디자인, 리서치의 모든 방법론을 외우기보다, 실제로 막히는 순간에 필요한 플러그인을 쓰도록 돕습니다. 이는 “필요해진 순간에 배우는” Just-in-Time Learning 원리와 닿아 있습니다.
3) 초보자용 도입 순서 설계
비전공 초보 개발자에게는 이 네 가지를 모두 설치하라고 권하지 않습니다. 첨부 자료의 핵심 제안처럼, 도구의 부재로 인한 불편을 경험한 뒤 필요한 한 가지를 도입하는 방식이 더 효과적입니다.
권장 순서는 다음과 같습니다.
먼저 Claude Code·Cursor 등 하나의 AI 코딩 도구로 작은 결과물을 만든다.
AI가 계획 없이 코드를 만들거나 검증을 빠뜨린다는 문제가 반복되면 Superpowers의 절차 원리를 참고한다.
프로젝트가 길어져 AI가 이전 결정을 잊기 시작하면 GSD식
SPEC,STATE,CONTEXT문서를 만든다.문서·회의록·아이디어가 쌓여 찾기 어려워지면 GBrain식 지식 축적 구조를 검토한다.
Git, 리서치, 문서화처럼 특정 단계가 계속 막히면 Gptaku의 문제 해결형 플러그인을 선택한다.
3. 결과와 배운 점
결과
이번 탐색을 통해 AI 에이전트를 단순히 “명령을 받아 코드를 생성하는 도구”로 보는 관점에서 벗어날 수 있었습니다. 좋은 에이전트는 좋은 모델 하나로 완성되지 않습니다. 절차가 있고, 기억을 남기며, 지식을 축적하고, 사용자가 막히는 순간에 도움을 주는 구조가 있어야 합니다.
특히 비전공 초보자에게는 도구의 성능 비교보다 “내가 지금 어디에서 막히고 있는가?”를 진단하는 능력이 더 중요하다는 점을 배웠습니다.
배운 점과 나만의 꿀팁
첫째, 프레임워크를 설치하기 전에 문제를 이름 붙여야 합니다.
“AI가 잘 안 된다”는 너무 넓은 표현입니다. 다음처럼 바꾸면 필요한 해결책이 보입니다.
“AI가 요구사항을 무시하고 기능을 추가한다” → 절차 문제, Superpowers 관점
“AI가 30분 전 결정을 잊는다” → 컨텍스트 문제, GSD 관점
“관련 자료가 많지만 답변 품질이 들쑥날쑥하다” → 지식 구조 문제, GBrain 관점
“Git이나 PRD에서만 계속 멈춘다” → 특정 역량 문제, Gptaku 관점
꿀팁: AI와 작업을 시작할 때 아래 네 문장을 먼저 메모하면 좋습니다.
1. 이번 작업의 최종 결과물은 무엇인가?
2. 현재 확정된 결정과 금지 사항은 무엇인가?
3. AI가 반드시 참고해야 할 자료는 무엇인가?
4. 사용자가 가장 자주 막힐 지점은 무엇인가?이 네 문장은 각각 명세, 상태, 컨텍스트, 도움말의 출발점이 됩니다.
둘째, README는 설치 매뉴얼이 아니라 설계 패턴 자료집입니다.
GitHub README를 볼 때 “설치 명령어가 무엇인가?”만 찾으면 활용 범위가 좁아집니다. 저는 다음 두 질문을 함께 읽는 습관이 유용하다고 봅니다.
이 프로젝트는 AI의 어떤 실패를 문제로 정의하는가?
그 실패를 막기 위해 어떤 절차·파일·역할·스킬을 배치했는가?
예를 들어 GBrain은 ‘무엇을 할지’보다 ‘어떻게 생각하고 상황에 맞춰 판단할지’가 필요한 것은 스킬로, 같은 입력에 같은 결과를 내는 조회나 상태 확인은 코드로 다룬다는 기준을 제시합니다. 비전공자도 이 기준을 쓰면, “이 기능을 프롬프트로 만들까, 자동화 규칙으로 만들까?”를 판단하는 데 도움이 됩니다.
셋째, 초보자는 “한 도구 완주”가 “도구 네 개 설치”보다 낫습니다.
프레임워크를 여러 개 함께 켜면 무엇이 어떤 효과를 냈는지 알기 어렵고, 도구 관리 자체가 새 인지부하가 됩니다. 처음에는 하나의 작은 프로젝트를 정하고, 한 가지 문제에 한 가지 원리만 적용해 보는 편이 좋습니다.
과정 중 겪은 시행착오
가장 큰 시행착오는 어려운 개념을 너무 일찍 설명하려 한 점입니다. 하네스, 오케스트레이터, 멀티에이전트 같은 개념은 흥미롭지만, 첫 결과물을 아직 만들지 못한 초보자에게는 추상도가 너무 높습니다. 이 단계에서는 용어를 많이 아는 것보다 “AI에게 요구사항을 주고, 실행 결과를 확인하고, 수정시키는 경험”이 먼저입니다.
또 다른 시행착오는 GitHub Star 수나 영상의 소개 문구를 곧바로 신뢰한 점입니다. 오픈소스 프로젝트는 빠르게 바뀌며, 마케팅 문구·기능·설치 방식이 실제 문서와 다를 수 있습니다. 따라서 실제 도입 전에는 README, 설치 문서, 라이선스, 릴리즈, 이슈 탭을 직접 확인해야 합니다. GSD Core도 공식 문서에서 최소 설치 후 필요한 스킬을 추가하는 접근을 안내하고 있어, 처음부터 기능 전체를 도입할 필요는 없습니다.
도움이 필요한 부분
앞으로 보완하고 싶은 부분은 두 가지입니다.
비전공자가 자신의 문제를 진단한 뒤, 네 가지 원리 가운데 무엇부터 적용할지 결정하는 자가진단 체크리스트
강의 참가자가 직접 자신의 업무를 대상으로
SPEC–STATE–CONTEXT문서를 만들고, 하나의 마이크로 스킬을 설계해 보는 실습용 템플릿
또한 이 글은 프레임워크의 설계 철학을 중심으로 정리한 것입니다. 각 프로젝트의 설치 명령, 지원 런타임, 스킬 수, 업데이트 상태는 바뀔 수 있으므로 실제 도입 시에는 반드시 공식 문서를 다시 확인해야 합니다.
앞으로의 계획
다음 단계에서는 이 글의 내용을 바탕으로 ‘내 업무용 LLM-wiki 에이전트 만들기’ 워크숍을 설계하려고 합니다.
워크숍 참가자는 코드를 많이 작성하기보다 다음 네 가지를 직접 완성하게 됩니다.
내 에이전트의 업무 절차를 정리한 프로세스 프롬프트
긴 작업을 이어가기 위한
SPEC,STATE,CONTEXT문서자료를 축적하고 다시 찾기 위한 개인 지식 위키 구조
반복적으로 막히는 일을 해결하는 작은 도움말 스킬 또는 프롬프트
궁극적으로는 “AI가 무엇을 할 수 있는가?”를 묻는 단계에서 벗어나, “내가 AI가 잘 일할 수 있는 환경을 어떻게 설계할 것인가?”를 질문하는 초보 개발자를 돕고 싶습니다.
4. 도움 받은 글
1) Superpowers 공식 README
요약: 브레인스토밍부터 작업공간 분리, 계획, 서브에이전트 실행, TDD, 코드 리뷰, 브랜치 종료까지 이어지는 AI 코딩 에이전트용 개발 워크플로우를 제시합니다.
참고 포인트: AI가 코드부터 생성하지 않게 하고, 계획과 검증을 절차에 포함시키는 방법을 이해하는 데 도움이 됩니다.
링크: obra/superpowers
2) GSD Core 공식 문서
요약: GSD Core는 컨텍스트 엔지니어링과 명세 기반 개발 프레임워크로, 긴 에이전트 작업에서 컨텍스트 품질이 저하되는 문제를 다루고 Discuss → Plan → Execute → Verify 루프를 안내합니다.
참고 포인트: 장기 프로젝트에서 요구사항, 현재 상태, 다음 작업을 별도 문서로 관리해야 하는 이유를 이해하는 데 유용합니다.
3) GBrain 공식 문서
요약: GBrain은 Markdown 기반의 개인 지식 브레인으로, 자료 수집·정제·검색·질의·인용 보정·스케줄링 등을 위한 스킬을 제공합니다. 데이터가 수집기→에이전트→브레인 페이지→인덱싱으로 흐르도록 설계합니다.
참고 포인트: 단순한 파일 보관이 아니라, 다음 질문에 더 나은 답을 주는 지식 축적 구조를 설계하는 데 참고할 수 있습니다.
4) Gptaku Plugins 한국어 README
요약: AI Native 사용자를 위한 Claude Code 플러그인 마켓플레이스입니다. 마켓플레이스 등록 후 필요한 플러그인을 선택해 설치하는 구조로 안내합니다.
참고 포인트: 초보자가 모든 기능을 한꺼번에 익히기보다, Git·문서화·PRD·리서치처럼 실제로 막힌 지점에 맞춰 도움 도구를 선택하는 방식에 참고가 됩니다.



