AI 코딩 에이전트용 오픈소스 Skill 'Agent Loop' 공개

프로젝트 주소: github.com/Shadow-linu… (현재 안정 버전 stable-v1.5.8, MIT 라이선스)

一、왜 이 프로젝트를 만드는가: AI 프로그래밍에 부족한 것은 "코드 작성"이 아니라 "클로즈드 루프"다

지금의 AI 프로그래밍 Agent(Claude Code, Codex, Kimi Code CLI, OpenCode……)는 코드를 작성하는 능력이 이미 매우 강력하다. 그러나 실제 프로젝트에서痛点(페인 포인트)는 흔히 "써내지 못하는 것"이 아니라 다음과 같다:

- 한마디 하면 한 줄 고치는 식, 프로세스가 없음 : 요구사항을 명확히 하지 않고 바로 쓰기 시작하고, 다 쓴 뒤에는 검증하는 사람이 없음;

- 기억이 없음 : 세션을 바꾸면 Agent는 이 프로젝트를 알아보지 못한다 — 과거의 결정, 제약, 밟아온 함정을 전부 처음부터 다시;

- 경계가 없음 : 사람에게 물어야 할 때 묻지 않고, 건드려서는 안 되는 프로덕션·배포 동작을 함부로 건드림;

- "코드 작성 완료"를 "일 완료"로 착각 : 테스트도, 리뷰도, 마무리도 없고, 복구 가능성은 말할 것도 없음.

Agent Loop는 바로 이 문제를 해결하기 위해 태어났다. 이것은 새로운 Agent도 아니고 프레임워크나 플랫폼도 아니며, 하나의 컨트롤러형(Controller) Skill 이다: "한 명의 인간 + 하나의 CLI Agent" 개발 모드를 지향하며, Agent가 프로젝트 진단, 프로세스 오케스트레이션, 구현, 검증, 기억 유지의 주도권을 갖게 하고, 인간은 항상 목표, 제품 의미론, 핵심 결정을 쥐고 있게 한다.

한마디로 요약한 설계 철학:

Human-directed · Agent-owned · Evidence-verified(인간이 방향을 정하고, Agent가 주도하며, 증거로 검증한다)

二、Agent Loop란 무엇인가

- 형태 : 하나의 표준 Agent Skill( SKILL.md + references/ 규칙집 + templates/ 템플릿)로, 기존 Code Agent에 설치하면 바로 사용할 수 있으며 작업 습관을 바꾸지 않아도 됨;

- 적응 : 국내외 주류 CLI Code Agent와 호환되며, 공식 원클릭 설치 명령이 Claude Code, Codex, Kimi Code CLI, OpenCode 등을 커버함; npx를 지원하지 않는 환경에도 Git 클론 설치 경로를 제공함;

- 포지션 : 이것은 "컨트롤러"다 — 현재 어느 단계에 있는지, 어느 규칙을 로드할지, 어떤 산출물을 만들거나 갱신할지를 결정하고, 인간 게이트(Human Gate) 앞에서 멈춘다.

메인 루프는 단 하나뿐이다:

인간 목표 → Agent Loop 컨트롤러 → 제품 정의 → 설계 준비 판단(필요 시 ADR) → 적절한 입도의 전달 → 신선한 검증과 리뷰 → 프로젝트 기억과 검증 클로즈드 루프

三、핵심 역량

1. 프로젝트를 이해하고 인수하기

- Message Intent Guard(메시지 의도 가드) : 먼저 당신의 이 말이 잡담인지, 요구사항인지, 운영 지원인지, Feature인지, Bug인지, 아카이브 유지보수인지 판단한 뒤에 산출물을 만들지 결정함 — "아무렇게나 두어 마디 얘기했다고 작업 공간을 잔뜩 만들어 주는" 일은 없음;

- Project Entry : 로컬 또는 원격 프로젝트를 초기화, 복구, 재인수하고, 수용된 프로젝트 기억 루트와 안전한 다음 단계를 제시함;

- Project Entry Scan + 증거 그래프 Onboarding : 저장소 구조, 명령, 경계, 진행 중 작업과 불확실 지점을 스캔하여, 증거로 뒷받침되고 신규 입사자 친화적인 프로젝트 인식 라이브러리( .agent-loop/onboarding-db/ )를 산출함;

- Root Guidance : 프로젝트 루트의 AGENTS.md / CLAUDE.md가 누락되었거나 오래되었는지 감지하고, 관리되는 수정을 제안함.

2. 코드를 쓰기 전에 요구사항을 명확히 성형하기

Agent Loop는 **적응형 제품 정의(Adaptive Product Definition)** 로 모호한 인간의 요청을 수용된 제품 정의로 바꾼다:

- 범위와 불확실성에 따라 브리핑급 또는 표준급 깊이를 선택하며, 무조건 큰 PRD를 만드는 것이 아님;

- Requirement Product Model : 역할, 권한, 명령, 이벤트, 흐름, 상태, 불변식, 예외와 복구를 도출하여, 안정적 ID를 갖추고 리뷰 가능한 제품 뷰를 형성함;

- Product Consensus : 먼저 증거를 조사하고 권장 답안을 제시하며, 한 번에 핵심 질문 하나만 물음 ;

- Requirement Lifecycle : 요구사항이 제기, 수용, 연기, 구현, 대체되기까지의 전 생애주기 관리로, 프로젝트 기억을 오염시키지 않음;

- Design Readiness / ADR : 공유 기술 설계가 필요한지 판단하고, 필요하면 인간이审定한 ADR로 정리함( .agent-loop/decisions/ ).

3. "최소 안전 워크플로"에 따라 등급별로 전달하기

Agent Loop는 모든 작업에 대해 일률적으로 무거운 프로세스를 밟지 않고, 위험에 따라 최소 안전 경로를 선택한다:

경로 적용 시나리오 통제와 증거 Chat 질의응답, 토론, 상태 기본적으로 어떤 요구사항이나 Feature도 생성하지 않음 Operational Support 코드 기반 테스트, 진단, 배포 리허설 읽기 전용 분석 우선, 변경은 반드시 게이트를 통과해야 함 Direct Edit Fast Path(1.5.8 신규) 진짜 사소하고, 확정적이며, 경계가 있고, 되돌릴 수 있는 소규모 변경 산출물 제로, 한 번의 정밀한 최종 검사 Lightweight Change Lane 영속화, 롤백, 더 넓은 검사가 필요한 일반 변경 월간 변경 카드 + 적응형 계획 + 수정 우선 검증 Feature 행동 / API / 상태 / 데이터 / 권한 / 아키텍처를 수반하는 경우 Spec → Tasks → Tests → TDD → Verify → Review Bug Follow-up 명확한 Bug: 식별, 증거, 중복 제거, 수정, 종료 bugs/ 디렉터리 + Feature가 관리하는 TDD 수정

부수 메커니즘에는 다음도 포함된다: 전 작업 공간 Git 커밋 패스트 트랙(모든 변경을 한 번에 보여주고, 인간이 확인한 뒤에만 git add -A ), 그리고 1.5.8에서 도입된 전체 테스트 일회 정밀 확인 ——새로 제안된 전체 테스트 매트릭스 또는 릴리스 스위트는 명령, 브랜치, 환경, 비용과 결론 주장을 명확히 해야 하며, 한 번의 승인은 기본적으로 한 번만 실행된다.

4. 검증, 리뷰와 클로즈드 루프: "코드 작성 완료" ≠ "완료"

완료에는 비례적이고 신선한 증거가 필요하다:

Execute → Verify → Review → Drift Check → Memory Update → Completion Check → 인간이审定한 Submit / Pause / Close

- 초기 Feature 구현과 명시적 Bug 수정 은 TDD를 강제함 (실제 RED/GREEN 증거);

- Feature 구축에는 의미 있는 리뷰가 단 두 번(정의 리뷰 + 구현 준비 리뷰)만 있으며, 내부 품질 단계로 당신을 방해하지 않음;

- Agent는 구현, 테스트, 요구사항과 결정의 커버리지, 무관한 변경, 오래된 문서, 롤백과 잔여 위험을 점검함.

5. 장기적으로 유지보수 가능한 프로젝트 기억

- .agent-loop/ 디렉터리에 프로젝트의 안정적 사실, 진행 중 작업, 복구 지점, 명령, 제약과 수용된 결정을 영속화함;

- 세션을 바꾸든 기계를 바꾸든 걱정 없음 : "이전 Agent Loop 작업을 계속해줘" 한마디면 가장 안전한 지점에서 복구됨;

- Drift & Recovery : 기억과 코드의 드리프트를 감지하고, 현재 코드, 환경과 인간의 권위로부터 역으로 채움;

- 완전한 Bug 관리, Feature 월간 아카이브 / 복구, 병합 후 기억 조정 메커니즘.

四、인간-기계의 권한과 책임: Agent가 가진 것, 인간이 보유하는 것

Agent가 가진 것:

- 먼저 증거를 조사한 뒤 질문하기;

- 현재 단계와 최소 안전 경로를 판단하기;

- 위험이 요구하는 깊이에 따라 계획하기;

- 구현, 테스트, 검증, 리뷰, 드리프트 수정과 문서 역채우기;

- 작업을 복구 가능하게 유지하고, 다음 단계를 추천하기;

- 권한 범위 안에서 검증이 완료되거나 진정한 Human Gate를 만날 때까지 계속 작업하기.

인간이 보유하는 것:

- 목표, 범위, 원천 요구사항과 수용된 제품 의미론;

- 중대한 영향을 미치는 제품 또는 기술 결정;

- 프로덕션, 유료, 키, 파괴적, 외부 서비스 동작;

- 브랜치 변경, commit, push, PR, 병합, tag, 릴리스;

- ADR, Feature 종료, Bug 종료 등 라이프사이클 게이트의 검수.

핵심 원칙: 하나의 게이트를 승인하는 것은 결코 다른 게이트를 승인하는 것이 아니다. Tag, Push, Release, Publish는 모두 독립적인 인간의 결정이다.

五、5분 만에 시작하기

원클릭 설치 (Node.js 18+ 필요):

npx -y skills add Shadow-linux/agent-loop \ --global \ --skill agent-loop \ --agent codex \ --agent kimi-code-cli \ --agent claude-code \ --agent opencode \ -- yes

어느 Agent에 설치할지 대화형으로 선택할 수도 있다: npx skills add Shadow-linux/agent-loop -g

프로젝트 인수하기 , 당신의 Agent에게 이렇게 말하라:

Use Agent Loop to take over this project. 먼저 현재 상황을 살펴보고, 그다음 우리가 합의한 작업을 내가 결정을 내려야 할 때까지 진척시켜줘.

프로세스 명사가 아니라 요구사항부터 시작하라:

제품 아이디어가 하나 있는데 아직 좀 거칠다. 손대기 전에 먼저 명확히 하는 걸 도와줘.

안전한 복구:

이전 Agent Loop 작업을 계속해줘. 먼저 현재 상태를 점검하고, 가장 안전한 지점에서 복구해줘.

六、마지막으로

AI 프로그래밍의 다음 단계는 모델이 더 빨리 쓰게 하는 것이 아니라, 전달 과정을 신뢰할 수 있게 만드는 것이다: 요구사항에는 근거가, 구현에는 증거가, 마무리에는 기억이 있고, 핵심 결정은 항상 사람의 손에 있다. Agent Loop는 이 엔지니어링 실천을 하나의 Skill로 압축해, 당신이 이미 쓰고 있는 Code Agent에 담아 넣는다.

이것이 당신에게 도움이 된다면, Star, Issue 제기, 또는 댓글로 "1인 + Agent" 개발에서 겪은 프로세스 문제를 이야기해 주기 바란다:

- GitHub: github.com/Shadow-linu…

- 안정 브랜치: stable-v1.5.8