본문으로 건너뛰기

GitHub 레퍼런스를 활용한 에이전트 설계와 개선 방법4 : 비전공 초보 개발자를 위한 AI 에이전트 설계 체크리스트

나대로

2026.08.11

이번에는 AI 에이전트를 만들고 싶지만 개발 경험이 많지 않은 분들을 위해, 복잡한 도구 설명보다 “무엇부터 설계해야 하는가”를 체크리스트로 정리해 보았습니다. 결론은 간단합니다. 좋은 에이전트는 화려한 모델이나 플러그인을 많이 연결해서가 아니라, 업무 절차·기억할 정보·지식의 출처·검증 방법을 먼저 설계할 때 더 안정적으로 작동합니다.


1. 시도하고자 했던 것과 그 이유

레슨런 1편에서는 GitHub 오픈소스를 단순 복사하는 대신, 좋은 구조와 원리를 내 문제에 맞춰 가져오는 벤치마킹과 전이의 관점을 다뤘습니다.

이번 글에서는 한 걸음 더 나아가, Superpowers·GSD Core·GBrain·Gptaku Plugins에서 발견한 설계 원리를 바탕으로 비전공 초보자를 위한 AI 에이전트 설계 체크리스트를 만들고자 했습니다.

제가 주목한 문제는 다음과 같습니다.

  • AI가 요청하지 않은 기능까지 만들거나, 계획 없이 결과부터 내놓는다.

  • 대화가 길어지면 앞에서 결정한 내용과 요구사항을 잊는다.

  • 참고 자료는 많지만, 필요한 순간에 근거 있는 답을 얻기 어렵다.

  • Git, 문서화, 리서치, PRD처럼 특정 업무 단계에서 반복적으로 막힌다.

  • 도구와 용어가 너무 많아, 초보자가 시작도 하기 전에 지친다.

Superpowers는 브레인스토밍·계획·테스트·리뷰 등 개발 절차를 에이전트 작업 흐름에 넣습니다. GSD Core는 컨텍스트가 누적될수록 품질이 저하되는 이른바 “context rot” 문제를 명세와 단계별 작업으로 다룹니다. GBrain은 Markdown 기반의 지식 저장소와 검색·수집·정제 스킬을 결합하고, Gptaku Plugins는 Claude Code 사용자가 실제로 막히는 문제를 작은 플러그인으로 해결하도록 돕습니다.

이 네 사례를 함께 보면, AI 에이전트 설계의 핵심은 결국 네 가지 질문으로 정리됩니다.

  1. AI가 어떤 순서로 일해야 하는가?

  2. AI가 무엇을 기억해야 하는가?

  3. AI는 어떤 근거와 지식을 참고해야 하는가?

  4. 사용자가 막힐 때 어떤 도움을 받을 수 있는가?

그래서 이번 시도는 특정 도구의 설치법을 알려 주는 데 있지 않았습니다. 비전공자도 자신의 강의, 행정, 컨설팅, 콘텐츠 제작, 소규모 서비스 업무에 맞춰 이 네 질문에 답하며 첫 에이전트의 설계도를 만들 수 있도록 돕는 데 목적이 있습니다.


2. 진행 방법

1) 도구가 아니라 실패 문제부터 정리하기

먼저 “어떤 도구가 좋은가?”를 묻는 대신, AI가 일을 잘 못하는 상황을 네 가지로 분류했습니다.

자주 겪는 문제

적용할 설계 원리

참고 사례

AI가 계획 없이 결과나 코드를 먼저 만든다

절차 설계

Superpowers

AI가 긴 작업에서 앞선 결정을 잊는다

컨텍스트 설계

GSD Core

자료는 많지만 맥락 있는 답을 얻기 어렵다

지식 설계

GBrain

특정 업무 단계에서 계속 막힌다

문제별 마이크로 스킬 설계

Gptaku Plugins

이 분류를 먼저 한 이유는, 프레임워크를 여러 개 설치해도 내 문제가 무엇인지 모르면 오히려 복잡성만 늘어나기 때문입니다.

예를 들어 AI가 요구사항을 무시하고 기능을 덧붙인다면, 더 많은 자료를 연결하는 것보다 “작성 전 계획을 먼저 제안하고 승인받기”라는 절차를 넣는 편이 효과적입니다. 반대로 긴 프로젝트에서 AI가 이전 결정을 잊는다면, 새로운 프롬프트를 길게 쓰는 것보다 SPEC–STATE–CONTEXT 같은 외부 문서로 맥락을 분리해야 합니다. GSD Core도 최소 핵심 기능부터 설치한 뒤 필요에 따라 스킬을 추가하는 방식을 안내합니다.

2) 체크리스트를 네 개의 레이어로 구성하기

다음으로 비전공자도 따라 할 수 있도록 체크리스트를 네 개의 설계 레이어로 나눴습니다.

A. 문제와 사용자 레이어

가장 먼저 “무엇을 만들까?”가 아니라 “누구의 어떤 불편을 해결할까?”를 한 문장으로 쓰도록 했습니다.

이 에이전트는 [사용자]가 [반복 문제]를 해결하여
[구체적 결과물]을 더 빠르고 일관되게 만들도록 돕는다.

예를 들어 “대학 강사를 위한 AI 에이전트”는 너무 넓습니다. 반면 아래 문장은 실제 설계의 출발점이 됩니다.

이 에이전트는 대학 강사가 흩어진 참고 자료를 정리해
90분 수업안과 활동지를 만드는 일을 돕는다.

B. 업무 절차 레이어

Superpowers의 기본 흐름은 아이디어를 질문으로 구체화하고, 설계를 승인받고, 세부 계획을 만든 뒤, 테스트와 리뷰를 거쳐 작업을 마무리하는 방식입니다.

이를 비전공자의 문서·교육·기획 업무에 전이하면 다음처럼 바꿀 수 있습니다.

요청 이해
→ 요구사항 확인
→ 목차·계획 제안
→ 사용자 승인
→ 초안 작성
→ 누락·근거·형식 검토
→ 최종 결과와 다음 행동 제안

이 흐름의 핵심은 AI에게 “만들어 줘”라고만 말하지 않는 것입니다. 먼저 무엇을 만들지 확인하고, 어떤 순서로 만들지 합의하게 하는 것입니다.

C. 컨텍스트와 기억 레이어

GSD Core는 명세 기반 개발과 단계별 작업 루프를 통해, 에이전트가 긴 작업에서도 맥락을 유지하도록 돕습니다. 문서에서는 논의, 계획, 실행, 검증의 단계가 각각 분리되어 있으며, 필요에 따라 새 컨텍스트의 서브에이전트를 활용하는 방식도 설명합니다.

이를 초보자용으로 단순화해 SPEC–STATE–CONTEXT 문서 세 개로 정리했습니다.

문서

기록할 내용

SPEC

목적, 사용자, 결과물, 성공 기준, 제외 범위

STATE

현재 단계, 완료한 일, 다음 할 일, 막힌 문제

CONTEXT

참고 문서, 용어 정의, 조직 규칙, 확정된 결정

이 세 문서는 사람에게도 필요합니다. 회의록 없이 긴 프로젝트를 진행하면 팀이 이전 결정을 잊듯이, AI도 작업의 기억을 별도 문서에 남겨야 일관성을 유지할 수 있습니다.

D. 지식과 도움말 레이어

GBrain은 일반 Git 저장소에 Markdown으로 지식을 축적하고, 이를 검색·수집·정제·질의·인용 보정 등으로 다시 활용하는 구조를 제안합니다. 공식 문서에서는 지식 저장소를 시스템의 기준 기록으로 두고, 에이전트 스킬을 Markdown 파일로 관리하는 방식을 설명합니다.

이 원리를 비전공자에게 적용하면 다음과 같습니다.

  • 자료를 무작정 많이 넣기보다, 먼저 어떤 질문에 답하기 위한 자료인지 구분한다.

  • 외부 사실, 내부 규정, 개인 의견, 오래된 기록을 한데 섞지 않는다.

  • 답변에는 참고한 근거와 출처를 남긴다.

  • 확실하지 않은 경우에는 그 사실을 분명히 밝히도록 한다.

Gptaku Plugins는 문제별 플러그인 방식의 좋은 사례입니다. 처음부터 모든 고급 기능을 가르치기보다, Git·문서화·리서치·PRD처럼 실제로 막히는 순간 필요한 도움을 고르는 방식입니다.

3) “문제를 겪은 뒤 도입” 원칙 적용하기

이번 체크리스트에서 가장 중요하게 둔 원칙은 다음입니다.

프레임워크는 미리 많이 설치하는 도구가 아니라, 실제 문제를 만난 뒤 선택하는 해결책이다.

예를 들어 초보자가 아직 AI로 간단한 결과물도 만들어 보지 못했다면, Superpowers·GSD·GBrain을 모두 설치할 필요가 없습니다. 우선 작은 랜딩페이지, 간단한 FAQ, 개인 업무용 문서 도우미처럼 한 가지 결과물을 끝까지 만드는 경험이 먼저입니다.

그 후 다음과 같이 필요한 원리만 추가하면 됩니다.

  • 계획 없이 결과가 나와 불안하다면 → 절차 설계

  • 긴 작업에서 AI가 앞을 잊는다면 → 컨텍스트 설계

  • 자료가 쌓여도 다시 활용하지 못한다면 → 지식 설계

  • 한 업무에서만 막힌다면 → 마이크로 스킬 설계

첨부 자료에서 강조한 것처럼, 학습자가 어떤 개념의 필요성을 느끼기 전에 어려운 메타 개념을 먼저 가르치면 인지부하가 커질 수 있습니다. 따라서 하네스, 오케스트레이터, 멀티에이전트 같은 용어는 첫 결과물을 만든 뒤 심화 과정에서 다루는 편이 좋습니다.


3. 결과와 배운 점

결과

이번 작업을 통해 AI 에이전트를 “질문하면 답하는 챗봇”이 아니라, 다음 네 요소로 구성된 업무 시스템으로 볼 수 있게 되었습니다.

  • 절차: AI가 어떤 순서로 일할 것인가

  • 기억: AI가 무엇을 잊지 않아야 하는가

  • 지식: AI가 어떤 근거를 바탕으로 답할 것인가

  • 지원: 사용자가 어디에서 도움을 받아야 하는가

이 관점은 비전공 초보자에게 특히 유용합니다. 코드를 잘 몰라도, 자신의 업무를 절차와 문서로 정리할 수 있다면 AI 에이전트의 품질을 개선할 수 있기 때문입니다.

배운 점과 나만의 꿀팁

첫째, AI 에이전트 설계는 도구 선택보다 문제 진단이 먼저입니다.

“AI가 잘 안 된다”는 말만으로는 해결 방법을 고를 수 없습니다. 아래처럼 구체적으로 진단해야 합니다.

  • AI가 앞뒤 맥락을 잊는다.

  • AI가 출처 없이 단정한다.

  • AI가 계획 없이 결과를 만든다.

  • AI가 특정 단계에서만 반복적으로 실패한다.

꿀팁: 에이전트가 기대와 다르게 동작할 때마다 다음 형식으로 한 줄 기록을 남기면 좋습니다.

[상황] 어떤 요청을 했는가?
[문제] 무엇이 기대와 달랐는가?
[원인 추정] 절차·기억·지식·도움말 중 무엇이 부족했는가?
[개선] 어떤 규칙 또는 문서를 추가할 것인가?

이 기록이 쌓이면, 프롬프트를 감으로 바꾸는 대신 내 에이전트만의 운영 매뉴얼을 만들 수 있습니다.

둘째, README는 설치 설명서가 아니라 설계 패턴 자료집입니다.

Superpowers는 반복 가능한 개발 절차를 스킬로 만듭니다. GSD Core는 명세·단계 루프·컨텍스트 관리를 중심에 둡니다. GBrain은 지식을 단순 보관하지 않고, 에이전트가 수집·정제·검색·답변에 활용할 수 있도록 설계합니다.

꿀팁: GitHub README를 읽을 때 아래 두 질문을 반드시 적어 보십시오.

  1. 이 프로젝트는 AI의 어떤 실패를 해결하려고 하는가?

  2. 그 문제를 막기 위해 어떤 규칙·문서·스킬·역할을 사용했는가?

이 두 질문은 오픈소스를 ‘설치 대상’이 아니라 ‘전이할 설계 원리’로 보게 만듭니다.

셋째, 스킬은 거대한 프롬프트가 아니라 반복 업무를 위한 작은 레시피입니다.

GBrain의 문서는 스킬을 에이전트가 읽고 따르는 Markdown 기반 절차로 설명합니다. Superpowers도 새로운 스킬을 만들 때, 실패 시나리오를 먼저 확인하고 그 실패를 줄이는 절차 문서를 작성한 뒤 다시 검증하는 접근을 제시합니다.

꿀팁: 처음 만드는 나만의 스킬은 아래처럼 작아야 합니다.

스킬 이름: 강의안 검토

실행 조건:
- 사용자가 강의안 또는 수업안을 붙여 넣었을 때

절차:
1. 학습 목표가 행동으로 표현됐는지 확인한다.
2. 학습자 수준에 비해 어려운 용어를 표시한다.
3. 활동과 평가가 학습 목표에 연결되는지 점검한다.
4. 수정 제안은 중요도 순으로 세 개만 제시한다.

출력 형식:
- 잘된 점 3개
- 보완할 점 3개
- 수정 예시 1개

처음부터 “만능 교육 에이전트”를 만들기보다, 이렇게 한 가지 반복 업무를 안정적으로 처리하는 작은 스킬부터 만드는 편이 훨씬 빠릅니다.

과정 중에 어떤 시행착오를 겪었나요?

첫 번째 시행착오는 프레임워크를 한꺼번에 많이 설명하려 한 점입니다. Superpowers, GSD, GBrain, Gptaku를 모두 소개하면 풍부해 보이지만, 초보자에게는 “그래서 무엇부터 해야 하지?”라는 부담으로 돌아올 수 있습니다.

두 번째 시행착오는 전문 용어를 너무 앞세운 점입니다. 하네스, 오케스트레이터, 컨텍스트 엔지니어링, 멀티에이전트는 중요한 개념이지만, 처음 AI 도구를 사용하는 사람에게는 결과물 제작보다 개념 암기를 강요할 위험이 있습니다. 첨부 자료가 지적하듯, 초보자에게는 첫 90분 안에 작동하는 결과물을 만드는 경험이 자기효능감 형성에 훨씬 중요합니다.

세 번째 시행착오는 GitHub Star 수, 영상 속 소개, 마케팅 문구를 곧바로 신뢰할 수 있다고 생각한 점입니다. 오픈소스 프로젝트는 릴리즈와 문서가 자주 바뀌므로, 실제 도입 전에는 공식 README·설치 문서·라이선스·이슈·릴리즈 노트를 직접 확인해야 합니다. GSD Core도 런타임별 설치 방식과 최소 설치 후 확장하는 방식을 공식 문서에서 별도로 안내합니다.

도움이 필요한 부분이 있나요?

앞으로 보완할 부분은 다음과 같습니다.

  • 비전공자가 자신의 문제를 진단하고, 절차·컨텍스트·지식·마이크로 스킬 중 무엇부터 설계할지 판단하는 자가진단 도구

  • 강의 참가자가 자신의 업무에 맞춘 SPEC–STATE–CONTEXT 문서를 즉석에서 작성하는 워크숍 템플릿

  • 교육자, 행정 담당자, 소상공인, 1인 창업자 등 서로 다른 직무별 에이전트 설계 사례집

  • AI가 사실과 의견을 구분하고, 자료 출처를 남기도록 하는 검증 프롬프트 템플릿

특히 비전공자 대상 워크숍에서는 “도구 설치 성공”보다 “자기 업무를 한 문장으로 정의하고, 한 가지 반복 문제를 해결하는 스킬을 만들었는가”를 성과 기준으로 삼는 것이 좋겠습니다.

앞으로의 계획이 있다면 들려주세요.

다음 단계에서는 이 글의 체크리스트를 실제 워크숍 실습으로 전환할 계획입니다.

참가자는 복잡한 에이전트를 한 번에 완성하는 대신, 다음 네 가지 산출물을 만들게 됩니다.

  1. 내 업무용 에이전트의 한 문장 목적문

  2. SPEC–STATE–CONTEXT 문서 초안

  3. 반복 업무 하나를 처리하는 마이크로 스킬

  4. 실제 업무 사례 세 개로 수행하는 테스트 기록

이후에는 이 결과물을 모아 “비전공자를 위한 LLM-wiki 에이전트” 형태로 확장하고 싶습니다. 최종 목표는 AI에게 막연히 일을 시키는 사용자가 아니라, AI가 잘 일할 수 있는 절차와 환경을 설계하는 사용자를 늘리는 것입니다.


4. 도움 받은 글

1) Superpowers 공식 README와 스킬 문서

  • 요약: Superpowers는 AI 코딩 에이전트가 브레인스토밍, 작업공간 분리, 계획, 서브에이전트 실행, 테스트 주도 개발, 코드 리뷰, 브랜치 마무리의 흐름을 따르도록 돕는 스킬 프레임워크입니다.

  • 참고한 점: 결과를 요청하기 전에 계획을 세우고, 결과 후에는 검증하는 “절차 우선” 설계 원리를 참고했습니다.

  • 링크: Superpowers GitHub Writing Skills: Superpowers

2) GSD Core 공식 문서

  • 요약: GSD Core는 AI 코딩 에이전트를 위한 컨텍스트 엔지니어링·명세 기반 개발 프레임워크입니다. 컨텍스트가 길어질수록 품질이 저하되는 문제를 다루며, 논의·계획·실행·검증의 단계 루프를 제공합니다.

  • 참고한 점: 초보자도 긴 작업에서 맥락을 놓치지 않도록 SPEC–STATE–CONTEXT 문서 구조를 설계하는 데 활용했습니다.

  • 링크: GSD Core GitHub GSD Core 문서

3) GBrain 공식 문서

  • 요약: GBrain은 Markdown 파일을 기반으로 개인 또는 팀 지식을 축적하고, 에이전트가 이를 수집·정제·검색·질의·인용 보정에 활용하도록 구성한 지식 브레인입니다.

  • 참고한 점: AI 에이전트가 자료를 단순히 검색하는 수준을 넘어, 출처를 바탕으로 맥락 있는 답을 만들도록 지식 구조를 설계하는 방법을 참고했습니다.

  • 링크: GBrain GitHub GBrain 개요 문서

4) Gptaku Plugins 한국어 README

  • 요약: Gptaku Plugins는 AI Native 사용자를 위한 Claude Code 플러그인 마켓플레이스입니다. 마켓플레이스를 등록한 뒤, 필요한 플러그인을 선택해 설치하는 방식으로 제공됩니다.

  • 참고한 점: 모든 기능을 한꺼번에 가르치기보다, Git·PRD·리서치·문서화처럼 실제로 막히는 시점에 필요한 작은 도움을 제공하는 방식에 참고했습니다.

  • 링크: Gptaku Plugins 한국어 README

함께 이야기해요 0

로그인하고 댓글을 남겨 주세요

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기