모든 팀에는 아무도 좋아하지 않지만, 항상 같은 방식으로 수행해야 하는 지루한 작업들이 있습니다. PR(Pull Request)을 표준 제목으로 여는 것, 올바른 브랜치를 명명하는 것, 변경 로그(changelog)를 작성하는 것, 워크 아이템(work item)을 연결하는 것이 그 예입니다. 이들은 지적 가치는 낮지만 주의 집중 비용이 높고 — 게다가 최악의 경우 표준에서 벗어난 모든 것은 검토 과정에서 노이즈가 됩니다.
저는 이를 다르게 접근하기로 했습니다. 거대한 bash 스크립트를 또 작성하는 대신, 이러한 흐름을 캡슐화하는 전문 AI 에이전트를 구축했습니다. 이 글에서는 Kiro CLI를 사용하여 어떻게 이 설정을 구조화했는지 보여드리며, 이때 설정(configuration), 지식(knowledge), 그리고 _안전 규칙(safety rules)_을 명확하게 분리하는 패턴을 사용했습니다.
제 내부 에이전트를 예시로 사용할 것이므로 (내부 이름은 추상화함), 이 패턴은 어떤 팀에도 적용될 수 있습니다.
문제점
일상생활에서 저는 하루에 여러 번 두 가지 흐름을 반복했습니다:
- Pull Request 열기: 표준 브랜치를 생성하고, 올바른 관례로 커밋한 후, 대상 브랜치를 추론하여, 표준화된 제목과 설명으로 PR을 열고 워크 아이템을 연결하는 것.
- 릴리스 패키지 닫기: 특정 요구사항에 대해 이미 완료된 PR들을 검색하고, 변경 로그를 생성하며, 커밋하고, 올바른 브랜치로 릴리스 PR을 여는 것.
이 단계들 중 어느 것도 어렵지는 않습니다. 문제는 이 모든 과정에 _세부 사항_이 있다는 것입니다 — 그리고 잊힌 세부 사항은 재작업으로 이어집니다. 순수 스크립트로 자동화하는 것은 취약할 수 있는데, 왜냐하면 결정의 상당 부분이 컨텍스트(어떤 브랜치인지, 어떤 제목인지, 어떤 대상인지)에 의존하기 때문입니다.
AI 에이전트는 바로 이 회색 지대에서 강점을 가집니다: 규칙을 따르지만 컨텍스트를 해석합니다.
핵심 아이디어: 설정, 지식, 규칙 분리
가장 도움이 된 것은 모든 것을 거대한 프롬프트에 담지 않은 것입니다. 대신, 각 에이전트를 네 개의 레이어로 나누었고, 각각은 별도의 파일로 구성했습니다:
.kiro/
├── agents/ # 설정: 에이전트가 사용할 수 있는 도구들
├── prompts/ # 정체성: 에이전트가 누구인지와 고정된 컨텍스트
...
핵심은 각 레이어가 고유한 책임을 가진다는 것입니다:
- Agent = o contrato (permitidas ferramentas, atalho, mensagem de boas-vindas)
- Prompt = a identidade (contexto que nunca muda)
- Steering = os limites (proibições inegociáveis)
- Skill = o manual (como executar cada passo, com exemplos)
이렇게 분리하면 엄청난 이점이 생깁니다: 스킬이 에이전트 간에 재사용 가능해집니다. '커밋 생성' 스킬은 PR을 여는 에이전트와 릴리스를 닫는 에이전트 모두에게 동일합니다.
레이어 1 — 에이전트 (설정)
에이전트의 설정 파일은 간결합니다. 에이전트가 무엇을 할 수 있는지 말할 뿐, 어떻게 하는지는 말하지 않습니다. 예시를 보겠습니다(추상화됨):
{
"name": "open-pr",
"description": "Pull Request를 여는 에이전트: 브랜치 생성, 커밋, PR 열기 및 작업 항목 연결.",
...
}
여기서 중요한 두 가지 포인트가 있습니다:
allowedTools는 명시적인 허용 목록(allowlist)입니다. 에이전트는 제가 나열한 도구만 정확하게 호출할 수 있습니다. 이는 설계상의 보안 기능입니다: 실수로 제가 승인하지 않은 파괴적인 도구를 호출하지 못합니다.resources는 스킬을 주입합니다. 에이전트는 모든 것을 항상 로드하는 대신, 필요할 때 상세한 지침을 불러옵니다.
레이어 2 — 프롬프트 (고정된 정체성과 컨텍스트)
프롬프트는 에이전트가 누구인지, 그리고 절대 변하지 않는 컨텍스트를 정의합니다. 여기서 저는 에이전트가 매번 당연한 것을 물어보는 것을 막기 위해 에이전트를 '닻 내립니다'.
You are an agent specialized in opening Pull Requests for the team's repository.
...
"규칙" + "무엇을 하지 말아야 하는지" 패턴에 주목하세요. 에이전트에게 무엇을 하지 말아야 할지 알려주는 것은 무엇을 해야 할지 알려주는 것만큼 중요합니다. 이는 예측 불가능한 행동을 크게 줄여줍니다.
팁: 유출되어서는 안 되는 데이터(내부 ID, GUID, URL)는 공개 아티클/문서에 포함되지 않으며 설정 또는 MCP를 통해 주입됩니다. 이를 열린 저장소로 가는 스킬 본문에 절대 넣지 마세요.
레이어 3 — Steering (절대적인 가드레일)
이것이 제가 마음 편하게 잠들 수 있는 계층입니다. 스티어링(steering)은 에이전트가 받는 어떤 지침과도 무관한 절대적인 금지 사항을 나열합니다.
# Open PR — Guardrails
## Proibições (금지사항)
...
_prompt_와 _steering_의 차이는 의도적입니다. 프롬프트는 페르소나(미묘한 뉘앙스를 가질 수 있음)이고, 스티어링은 법률(예외가 없음)입니다. 사용자가 '강제 푸시(force push) 해줘'라고 요청하더라도, 가드레일이 막아섭니다.
계층 4 — Skills (재사용 가능한 지식)
스킬(skills)은 설정의 핵심입니다. 각각은 하나의 절차를 가르치는 짧은 문서이며, 형식과 예시가 포함됩니다. 예를 들어 커밋 스킬(skill of commit)은 전체 규칙을 정의합니다:
강점은 이겁니다: 동일한 커밋 스킬이 PR 에이전트와 릴리스 에이전트 모두에 사용됩니다. 한 번 작성하면 모든 곳에서 재사용합니다. 규칙이 변경되면 파일 하나만 수정합니다.
제 두 번째 에이전트인 릴리스 종료 에이전트는 기본적으로 **스킬의 오케스트레이션(orchestration)**입니다:
요구사항 ID를 받음
→ 이미 완료된 PR들을 검색
→ 올바른 브랜치로 전환
...
즉, 복잡한 에이전트는 단순한 스킬들의 조합으로 탄생합니다. 이는 단일(monolithic) 프롬프트보다 유지 관리가 훨씬 쉽습니다.
계층 5 — MCP를 통한 통합
에이전트가 실제로 PR을 열고 요구사항을 검색하려면, Git 제공업체와 통신해야 합니다. 저는 이를 **MCP (Model Context Protocol)**를 통해 수행하는데, 이는 외부 작업을 에이전트가 호출할 수 있는 도구로 노출합니다.
{
이 설정이 워크플로우에 통합된 후, PR(Pull Request)을 여는 것이 하나의 문장으로 바뀌었습니다. _“요구사항 X에 대한 PR 열어줘”_라고 말하는 식이죠. 에이전트는 브랜치를 추론하고, 표준 형식으로 커밋하며, 올바른 제목과 설명으로 PR을 열고 작업 항목(work item)까지 연결합니다. 항상 같은 방식으로, 제가 모든 세부 사항을 기억할 필요가 없습니다.
그리고 저장소의 커밋 기록을 보면, 일관된 규칙이 지켜지고 있다는 것을 알 수 있습니다. 예를 들어, 범위(scope), 이모지, 그리고 짧은 영어 설명이 커밋마다 반복됩니다. 이러한 일관성이 제가 원했던 바로 그것입니다. 그리고 이것은 더 이상 피곤한 날 제 기억력에 의존하지 않습니다.
## 모든 프로젝트에 적용할 교훈들
만약 제가 배운 점을 재사용 가능한 원칙으로 요약한다면 다음과 같습니다:
1. **설정(Configuration)과 지식(Knowledge)을 분리하세요.** 에이전트는 _무엇을 할 수 있는지_를 말하고, 스킬(skill)은 _어떻게 할지_를 알려줍니다.
2. **가드레일(Guardrails)은 별도의 계층이어야 합니다.** 금지 사항은 일반적인 지침과 섞여서는 안 됩니다.
3. **작고 재사용 가능한 스킬로 구성하세요.** 복잡한 에이전트는 단순한 스킬들의 조합입니다.
4. **항상 도구의 허용 목록(Allowlist)을 사용하세요.** 신뢰가 아닌 설계 단계부터 보안을 확보해야 합니다.
5. **무엇을 '하지 말아야' 할지 명시하세요.** 이는 어떤 긍정적인 지침보다 예측 불가능한 행동을 줄여줍니다.
6. **민감한 데이터는 스킬 외부로 유지하세요.** 버전 관리되는 텍스트에 넣지 말고, 설정 또는 MCP를 통해 주입해야 합니다.
결국 저는 단순히 작업을 자동화한 것이 아니라, _의사 결정 과정 자체를 표준화했습니다_. 그리고 이것이 시간 절약보다 저의 워크플로우를 바꾼 핵심 요소였습니다.
만약 여러분도 Git에서 반복적인 단계를 겪는다면, 이 패턴을 시도해 볼 가치가 있습니다. 커밋과 같은 하나의 스킬부터 시작해서 점차 조합을 늘려가 보세요.
🇺🇸 English version: [How I turned repetitive Git chores into AI agents with the Kiro CLI](https://dev.to/indiorlei/how-i-turned-repetitive-git-chores-into-ai-agents-with-the-kiro-cli-19h4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23