AGENTS.md

1. 문서 다운로드

원본 주소https://www.repl.net/documents/agents.md

AGENTS.md 원본 보기 Markdown 다운로드

원본 주소https://www.repl.net/scripts/ask-human.sh

ask-human.sh 원본 보기 Markdown 다운로드

2. 개요 및 목적

AGENTS.md는 시작 전에 필요한 질문을 하고, 사람의 승인이나 권한이 필요한 지점에서는 멈추면서 TASKS.md의 작업을 순서대로 수행하는 자동 실행 지침입니다.

"How can AI complete the project tasks continuously? (AI가 프로젝트 작업을 끝까지 어떻게 수행할 것인가?)"

3. 사용 방법

가장 편한 방법은 repl-cli를 이용하는 것입니다.

1. repl-cli 설치

brew install replworks/tap/repl

macOS, Linux, Windows용 사전 빌드 아카이브는 GitHub Releases에서 받을 수 있습니다. Linux에서는 replworks APT 저장소의 .deb 패키지도 사용할 수 있습니다.

자세한 내용은 Tools의 REPL CLI 또는 repl-cli 저장소를 참고하세요.

2. 문서 생성

프로젝트 루트에서 다음 명령을 실행합니다.

repl init

실행하면 최신 AGENTS.md와 함께 templates/scripts/ask-human.sh가 설치됩니다. ask-human.sh은 AUTO_RUN에 필요한 스크립트입니다.

3. 최신 문서로 업데이트

언제든지 다음 명령으로 최신 문서로 업데이트할 수 있습니다.

repl sync

4. 실행 정보 준비

문서가 요구하는 계정, 커밋 작성자, 공동 작성자 정보를 시작 프롬프트에 함께 제공합니다. 정보가 없으면 에이전트가 먼저 질문합니다.

5. 작업 시작 요청

프로젝트의 AI 에이전트에게 작업을 시작하라고 요청합니다. 에이전트는 권위 문서를 읽고, 필요한 질문을 한 뒤 답변을 받은 다음 TASKS.md의 첫 번째 미완료 작업부터 수행합니다.

6. 승인 요청 처리

PR 생성, 리뷰, 병합, 권한 부여처럼 사람의 승인이 필요한 단계에서는 에이전트가 멈추고 승인을 요청합니다. 모바일 환경에서도 해당 승인 요청을 확인하고 처리한 뒤 작업을 계속할 수 있습니다.

4. 시작 시 Bootstrap 프롬프트

AUTO_RUN을 시작할 때는 반드시 아래 bootstrap 프롬프트를 AI 에이전트에게 그대로 전달해야 합니다. 실행 정보(계정, 커밋 작성자, 공동 작성자)와 함께 제공합니다.

AGENTS.md 읽어. 그리고 TASKS 개발 시작해.

아래는 AGENTS.md의 "Stop and ask the human"을 어떻게 수행하는지에 대한 추가 규칙이다.
AGENTS.md의 다른 규칙은 하나도 바꾸지 않는다. 충돌하면 AGENTS.md가 우선이다.
단, "사람에게 묻는 방법"만은 이 규칙을 따른다.

## 질문 방법

### 1단계: 첫 태스크 브랜치를 만들기 전 (bootstrap)
- 지금처럼 세션 대화창에서 나에게 직접 묻는다.
- ask-human.sh 를 쓰지 않는다. 폴링하지 않는다.

### 2단계: 첫 태스크 브랜치를 만든 이후 (AUTO_RUN 시작 후)
- 나에게 물어야 하는 상황(AGENTS.md의 "Stop and ask" 조건)이 생기면
  세션 대화창에 질문을 쓰고 턴을 끝내지 않는다.
  반드시 GitHub 코멘트로 묻고, 내 답이 올 때까지 기다렸다가 이어서 진행한다.
- 질문하지 않고 추측해서 진행하지 않는다.

채널 선택:
- 현재 브랜치에 코드 변경이 있다(main 대비 커밋이 있거나 커밋 안 된 변경이 있다)
  -> PR 채널
- 코드 변경이 없다 -> Issue 채널

PR 채널:
1. 현재 브랜치에 PR이 없으면: 커밋 안 된 변경은 `chore: wip t-NNN` 으로 커밋(bot account),
   브랜치를 push 하고 bot account 로 draft PR을 연다
   (Conventional Commits 제목, assignee: bot account).
   이 draft PR이 그 태스크의 최종 PR이다. 두 번째 PR을 만들지 않는다.
   태스크가 끝나면 이 PR을 ready 로 전환해서 AUTO_RUN 6번을 수행한다.
2. `.replworks/scripts/ask-human.sh ask pr "<질문>"` 을 실행한다.

Issue 채널:
1. `.replworks/scripts/ask-human.sh ask issue "<질문>"` 을 실행한다.
   질문 하나에 이슈 하나다. 질문 때문에 커밋/push/PR을 만들지 않는다.

질문 형식:
- 객관식을 기본으로 하되, 안 맞으면 자유 응답 허용. 선택지 2~4개, 각 한 줄.
- 권장안에 "(recommended)" 를 붙인다.
- 코드가 어떻게 동작하는지가 아니라 "무엇이 맞는지"를 묻는다.
- 관련 문서 섹션이나 diff 링크를 넣는다.
- 나는 폰에서 5초 안에 답한다고 생각하고 쓴다.

답 기다리기:
1. ask 가 출력한 값이 토큰이다. `.replworks/scripts/ask-human.sh wait <토큰>` 을 실행한다.
2. 출력이 `PENDING` 이면 같은 명령을 그대로 다시 실행한다. 최대 120회 반복한다.
   반복하는 동안 다른 작업이나 설명을 하지 않는다.
3. `PENDING` 이 아니면 그 출력이 내 답이다. 답대로 이어서 진행한다.
4. 내 답을 받으면 그 코멘트에 이모지를 단다: 읽고 진행하면 `+1`, 모호해서 재질문하면 `confused`, AGENTS.md와 충돌해서 못 하면 `-1`
5. 120회가 지나도 답이 없으면, 어느 태스크의 어떤 조건에서 기다리는지를
   그 PR 또는 이슈에 코멘트로 남기고 멈춘다.
   TASKS.md 를 수정하지 않는다. 임의로 진행하지 않는다.

ask-human.sh 가 에러를 내면(PR 없음 등) 에러 메시지를 읽고 위 절차대로 고친 뒤 다시 실행한다.
스크립트 자체가 동작하지 않으면 그 사실을 세션 대화창에 보고하고 멈춘다.

5. 문서 순서 및 자동 실행 범위

AGENTS.md는 다음 문서 순서를 따릅니다.

AGENTS.md (프로젝트 헌법 & 자동 실행 진입점)

.replworks/PRODUCT_SPEC.md (제품 명세)

.replworks/TECH_STACK.md (기술 구현 규칙)

.replworks/ARCHITECTURE.md (시스템 설계)

.replworks/TASKS.md (순서대로 수행할 작업 목록)

에이전트는 한 번에 하나의 작업을 수행하고 테스트한 뒤, 사람 계정으로 커밋하고 봇 계정으로 PR을 생성합니다. 모든 CI 검사가 통과하면 PR을 병합하고 다음 작업으로 넘어갑니다. 문서 충돌, 확인되지 않은 요구사항, 외부 경계 접근 실패, 테스트 실패, 개발자 결정이 필요한 상황에서는 자동으로 진행하지 않고 사람에게 질문합니다.