이 페이지는 AI 어시스턴트인 Claude Code, Codex, Cursor 또는 웹 페이지를 읽고 사용자의 로컬 저장소 복사본에서 작업할 수 있는 모든 어시스턴트를 위한 실행 가이드입니다. 이 가이드는 어시스턴트가 하나 이상의 저장소에 대해 Coroid를 설정하는 과정을 안내합니다. 로그인, 접근 권한 부여, 비밀번호 입력, 변경 사항 승인 등 사람만 할 수 있는 단계마다 사용자에게 멈춰서 확인을 요청합니다.
어시스턴트에게 전달하기
Coroid가 작업할 저장소에서 어시스턴트를 열고 다음 프롬프트를 입력하세요:
Set up Coroid for this repository. Follow the runbook at
https://coroid.ai/docs/export/en-US/getting-started/assistant-setup.md
step by step. Ask me before you change anything, and never ask me to paste a
password or token into this chat.여러 저장소의 경우, 이를 모두 포함하는 디렉터리에서 어시스턴트를 열고 프롬프트에 저장소 이름을 명시하세요. 어시스턴트가 검사와 확인을 수행한 뒤, 사용자가 개입해야 하는 각 단계에서 정확히 무엇을 해야 하는지 알려줍니다.
어시스턴트를 위한 기본 규칙
사용자는 작업을 지시하고, 어시스턴트는 준비합니다. Coroid는 호스팅되는 AI 소프트웨어 팩토리로, 작업 설명을 사용자의 저장소에 있는 테스트되고 검토된 pull request로 변환합니다. 다음 규칙을 반드시 준수하세요:
- 사용자가 행동하고, 어시스턴트가 준비합니다.사용자를 대신해 가입, 로그인, 약관 동의, 앱 설치 또는 접근 권한 부여를 할 수 없습니다. 정확히 무엇을 어디서 해야 하는지 알려준 뒤, 사용자가 완료했음을 확인할 때까지 기다리세요.
- 대화 내용에 비밀 정보를 포함하지 마세요.절대 암호, 개인 액세스 토큰, 제공업체 키 또는 MCP 토큰을 요청하지 마세요. 사용자는 Coroid 포털이나 자체 셸에 비밀 정보를 입력합니다. 만약 채팅에 이러한 정보가 붙여넣어진다면, 사용자에게 해당 토큰을 취소하고 새로 생성하도록 알려주세요.
- 변경 전에 항상 확인 요청하기: 사용자 저장소, Coroid 프로젝트 및 초대장 내의 커밋, 브랜치, 풀 리퀘스트 등
- 다음 단계로 넘어가기 전에 각 단계를 확인하세요.만약 검사에 실패하면 해당 단계의 안내를 따르고, 통과하거나 사용자가 건너뛰기로 결정할 때까지 진행하지 마세요.
- 제품의 실제 동작을 따르고, 추측은 하지 마세요.만약 포털에 이 실행 가이드에 설명되지 않은 내용이 표시된다면, 사용자에게 보이는 내용을 알려주고 포털의 안내를 따르세요. 임의로 설정을 만들어내지 마세요.
- 설정 기록을 남겨두세요각 단계와 그 결과를 끝까지 기록해 두세요.
각 단계는 세부 정보가 담긴 페이지와 연결됩니다.https://coroid.ai/llms.txt전체 문서를 색인화합니다.
1단계: 계획 합의하기
다음 질문들을 한 번에, 순차적으로가 아닌 사용자에게 물어보세요:
| 질문 | 중요성 |
|---|---|
| Coroid가 작업할 저장소는 어떤 것인가요? | 저장소당 프로젝트는 하나씩입니다. |
| GitHub인가요, 아니면 GitLab인가요? 개인 소유인가요, 조직 소유인가요? | 이에 따라 Coroid의 연결 방식과 승인 권한이 결정됩니다. |
| Coroid가 풀 리퀘스트를 생성해야 할까요(동기화됨), 아니면 처음에는 Coroid 내부에서 작업을 유지해야 할까요(로컬 전용)? | 로컬 전용 모드에서는 절대 안 함 저장소에 쓰기 작업을 수행하지 않습니다. |
| Coroid 조직이 이미 존재하며, 어떤 계획을 사용 중인가요? | 무료 버전은 프로젝트 1개만 지원하며 다른 멤버는 추가할 수 없습니다. |
| 누가 작업을 검토하며, 어떤 역할로 참여하나요? | 멤버를 초대하려면 Professional 계획이 필요합니다. |
| Coroid에서 조직의 기존 모델 제공업체 키를 사용해야 할까요? | 선택 사항입니다. Coroid가 라우팅하는 모델의 경우 별도의 키가 필요하지 않습니다. |
그런 다음 아래 단계들을 다시 확인해 주세요. 사용자가 직접 수행해야 하는 작업과 적용 범위에 포함된 저장소들입니다.
다음을 참조하세요:계획 및 요금 정보, 제한 사항 및 할당량및동기화 또는 로컬 전용.
2단계: 각 저장소가 깨끗한 클론에서 빌드 및 테스트되는지 확인하기
이것은 가장 유용한 작업입니다. 모든 Coroid 작업은 깨끗하고 일회성인 Linux 워크스페이스에서 실행됩니다. 즉, 새로운 클론을 만들고 캐시된 데이터나 설치된 종속 요소 없이 이미지에 포함된 도구 체인만 사용합니다. 프로젝트를 빌드하고 테스트할 수 없는 에이전트는 자신의 작업을 검증할 수 없으며, 변경 사항과 무관한 이유로 작업 검증에 실패하게 됩니다.
저장소에서 로컬로 작업할 수 있다면, 각 저장소에 대해 다음을 수행하세요:
- 사용 언어, 패키지 관리자, 그리고 모노레포인지 확인하세요.
- README, CI 설정 파일 및 매니페스트에서 설치, 빌드, 테스트 명령어를 찾아보세요.
- 실행하기 전에 반드시 확인하세요. 그런 다음 저장소를 비어 있는 임시 디렉터리에 클론하고, 다른 설정 없이 설치, 빌드, 테스트를 진행하세요. 사용자의 작업 복사본에는 캐시 및
.env파일이 있어서 문제를 숨길 수 있습니다. - 깨끗한 클론에서는 누락된 실행에 필요한 항목들을 모두 기록해 두세요:
- 테스트에서 요구하는 데이터베이스, 캐시 또는 큐와 같은 서비스들
- 코드 생성, 마이그레이션 또는 Fixture와 같이 테스트 전에 필요한 단계들
- 환경 변수 또는
.env커밋되지 않은 파일 - 비공개 패키지 레지스트리
- 이미지에 포함되지 않은 런타임 에이전트 환경
배포, 게시 또는 공유 환경을 변경하는 명령은 절대 안 함 실행하세요. 만약 테스트 스위트가 느리거나 유료 서비스를 호출한다면, 먼저 사용자에게 확인하세요.
각 저장소별로 간단한 준비 상태 점검 보고서를 작성하세요: 실행한 명령어, 테스트 스위트 실행에 걸린 시간, 통과한 항목, 그리고 제안된 수정안이 포함된 각 불일치 사항을 기재합니다.
| 불일치 사항 | 제안할 수정안 |
|---|---|
| 테스트를 위해 데이터베이스나 다른 서비스가 필요합니다. | 테스트 스위트와 해당 서비스를 실행하는 Dockerfile 또는 Compose 파일입니다. |
필수적인.env파일이 커밋되지 않았습니다. | 코드 내에 테스트 기본 설정을 정의하거나, 비밀 값이 아닌 항목으로 구성된 커밋된 테스트 설정 파일을 사용하세요. |
| 테스트에 실제 비밀 값이 필요합니다. | 테스트에서 해당 종속성을 모의 처리하세요. 절대 비밀 값을 커밋하지 마세요. |
| 종속성은 프라이빗 레지스트리에서 가져옵니다. | 사용자에게 알려주세요. Coroid는 프로젝트 설정으로 해당 정보에 대한 인증 정보가 필요합니다. |
| 명령어는 하위 디렉터리에서만 정상적으로 작동합니다. | 정확한 디렉터리 경로와 워크스페이스 필터를 기록해 두세요. |
런타임이 누락된 경우도 장애 요인이 되지 않습니다. 툴체인이 포함된 컨테이너를 사용하면 이 문제를 해결할 수 있습니다. 로컬에서 저장소에 접근할 수 없다면 사용자로부터 가능한 정보를 수집하고, 클린 클론 점검이 수행되지 않았음을 기록해 두세요.
참고:빌드 및 테스트 설정와언어 지원 및 에이전트 환경.
3단계: Coroid의 에이전트가 읽을 수 있는 지침을 작성하세요.
모든 작업을 수행하기 전에 Coroid의 에이전트는 저장소 내의 메모리 파일을 읽습니다:AGENTS.md, CLAUDE.md또는GEMINI.md루트 디렉터리에 위치하며,.cursor/rules.
2단계에서 확인한 명령어를 여기에 기재하세요.
다음과 같은 내용을 담은AGENTS.md을 제안하거나 기존 파일에 추가하세요. 내용은 다음과 같아야 합니다:
- 클린 클론 환경에서 확인된 설치, 빌드, 테스트 명령어와 이를 실행할 디렉터리 정보입니다.
- 테스트에 필요한 단계와 서비스 목록입니다.
- 특정 패키지나 파일만을 대상으로 하는 최소한의 유용한 테스트 세트를 실행하는 방법입니다.
- 코드 자체에는 드러나지 않는 규칙과 제약 사항: 사용이 금지된 모듈, 수정이 허용되지 않는 영역, 추가가 금지된 종속성 등입니다.
코드에 이미 명시된 내용은 제외하고 파일 크기를 최소화하세요. 만약CLAUDE.md또는.cursor/rules에 동일한 지침이 포함되어 있다면, 이를 한 번만AGENTS.md에 기재하고 다른 파일에서는@AGENTS.md줄을 사용해 불러오세요.
사용자에게 변경 내용을 보여주세요. 사용자의 승인을 얻으면 새 브랜치에 커밋하고 pull request를 생성하거나, 사용자가 직접 커밋하도록 남겨두세요. 첫 번째 작업이 시작되기 전에 이 변경 사항이 기본 브랜치에 반영되어야 합니다. 각 작업은 해당 브랜치의 체크아웃본에서 메모리 파일을 읽기 때문입니다. 2단계에서 사용자가 승인한 수정안도 동일한 방식으로 처리하세요.
4단계: 계정 및 조직(사용자)
해당 사용자가 이미 Coroid 조직의 소유자 또는 관리자라면 이 단계는 건너뛰세요.
사용자에게 다음을 요청하세요:
- 에서 가입하도록 안내하세요
https://client.coroid.ai/auth/signup업무용 이메일로 가입한 뒤 주소를 인증해야 합니다 - 서비스 이용 약관에 동의해야 합니다
- 조직을 생성해야 합니다
확인 사항:사용자가 를 열 수 있는지 확인하세요https://client.coroid.ai/projects. 이 설정을 완료하는 사람은 소유자 또는 관리자 역할이 필요합니다. 해당 역할만이 소스 제어 시스템을 연결하고 제공업체 키를 추가할 수 있기 때문입니다.
다음을 참고하세요계정 및 조직 생성하기.
5단계: 소스 제어 시스템 연결(사용자)
시작하기 전에 사용자의 접근 권한 요건을 미리 확인하세요. 다른 사람의 승인을 기다리느라 설치 과정이 중단되는 경우가 흔히 발생하며, 이로 인해 이 단계가 1분이 아닌 하루가 걸리기도 합니다.
GitHub
사용자는 를 엽니다설정 → 연결 → 소스 제어
(https://client.coroid.ai/settings/connections/source-control).
| 옵션 | 다음의 경우에 사용하세요 | GitHub에서 사용자가 필요로 하는 항목 |
|---|---|---|
| GitHub 앱(권장) | 거의 항상 | 저장소를 소유한 계정 또는 조직에 앱을 설치할 수 있는 권한이 필요합니다. 조직 내에서는 보통 소유자에게 이 권한이 부여되며, 다른 구성원은 소유자의 승인을 받아 설치를 요청할 수 있습니다. |
| 개인 액세스 토큰 | 앱이 사용자가 얻을 수 없는 승인을 필요로 하는 경우 | 범위를 가진 기존 토큰 또는repo에 대한 읽기 및 쓰기 권한을 가진 세밀하게 설정된 토큰콘텐츠및풀 리퀘스트선택한 저장소에 대해 적용됩니다 |
| URL로 연결, 연결 없음 | 공개 저장소로, 에서 테스트했습니다로컬 전용 | 없음 |
GitHub 앱:GitHub의 설치 화면에서 사용자는 을 선택합니다저장소만 선택하세요그리고 1단계에서 합의된 항목을 선택합니다. 해당 앱은 설치한 사용자가 떠나도 계속 작동하며 웹훅 이벤트를 수신하고, 이를 통해 Coroid가 풀 요청에 대한 검증 결과를 게시할 수 있습니다. 토큰으로는 GitHub 검증 결과를 게시할 수 없습니다.
개인 액세스 토큰:사용자는 GitHub에서 만료 기한이 지정된 토큰을 생성한 뒤, 이를 Coroid 포털에 붙여넣습니다. 합의된 저장소에만 접근할 수 있도록 범위가 제한된 세밀한 권한의 토큰을 사용하는 것이 좋습니다. 풀 요청은 토큰의 소유자를 기준으로 할당되며, 해당 사용자의 접근 권한이 상실되면 연결이 끊어집니다.
GitLab
GitLab는 비공개 미리보기 단계에 있으며, 기능이 활성화된 계정에만 표시됩니다. 이 기능은 다음과 같은 범위를 가진 개인 액세스 토큰과 연동됩니다.api만약 GitLab이 소스 제어 목록에 나타나지 않으면, 사용자에게 Coroid에 문의하도록 안내하고 이를 기반으로 계획을 세우지 마세요.
브랜치 보호
Coroid는 일반적인 풀 요청을 생성하므로 브랜치 보호, 필수 검증 및 리뷰 규칙이 여전히 적용됩니다. 보호 기능을 유지하는 것을 권장합니다. 만약 규칙에서 서명된 커밋이나 Coroid가 생성할 수 없는 상태 검증을 요구한다면, 해당 풀 요청은 열린 채로 병합될 수 없게 됩니다. 사용자에게 이를 알려주고 규칙을 변경하지 마세요.
검증:제공업체가 소스 제어 목록에 연결된 것으로 표시됩니다. 실제 증거는 6단계에서 저장소가 프로젝트 목록에 나타날 때 확인할 수 있습니다.
다음을 참조하세요코드 연결하기, GitHub, GitLab그리고저장소 및 브랜치 설정.
6단계: 프로젝트 생성(사용자)
저장소당 하나의 프로젝트를 생성하며, 하나의 저장소에 대해 두 개의 프로젝트를 만들지 마세요. 사용자는프로젝트 → 새로 만들기 (https://client.coroid.ai/projects/new) 그리고 각 저장소마다:
- 연결된 제공업체에서 선택하거나URL로 연결를 사용하여 공개 저장소를 추가합니다.
- 다음을 선택합니다저장소 모드: 동기화 모드에서는 Coroid가 브랜치를 푸시하고 풀 요청을 생성하며, 로컬 전용 모드에서는 누군가동기화 시작
- 기본 브랜치를 확인합니다.
- 프로젝트를 생성합니다.
만약 팀에서 기본 브랜치가 아닌 다른 브랜치로 병합한다면, 예를 들어develop와 같이, 프로젝트의 저장소 설정에서 기본 브랜치를 지정해야 합니다. 잘못된 기본 브랜치를 설정하면 아무도 검토하지 않는 브랜치로 풀 요청이 전송됩니다.
만약 목록에 저장소가 표시되지 않으면, 원인은 거의 다음 중 하나입니다:
- GitHub 앱에 해당 저장소에 대한 접근 권한이 부여되지 않았습니다.
- 토큰의 범위가 너무 좁아서 저장소를 목록에 표시할 수 없습니다.
- 해당 저장소가 연결된 조직과 다른 조직에 속해 있습니다.
다음을 참조하세요첫 번째 프로젝트 생성및저장소 및 브랜치 설정.
7단계: Coroid가 찾은 내용 확인
사용자에게 각 프로젝트의 개요 페이지를 열어서 다음 내용을 읽어달라고 요청하세요저장소세부 정보와 그 아래에 나열된 항목을 확인하세요설정 완료:
- 상태및브랜치: 지정한 기본 브랜치에 저장소가 복제됩니다. 개요에 저장소가 아직 복제되지 않았다고 표시되면 사용자는저장소 복제.
- 스택: Coroid가 감지한 언어, 프레임워크, 패키지 관리자 및 테스트 도구입니다. 이를 준비 상태 확인 결과와 비교해 보세요. 첫 동기화 후 스택이 비어 있거나 잘못된 경우 사용자는 거기서 다시 스캔할 수 있습니다.
- 설정 완료: "종속성 설치가 제대로 되지 않음"과 같은 항목은 2단계에서 발견된 동일한 문제를 가리킵니다. 사용자와 함께 이 문제들을 해결하세요.
그런 다음 사용자는 프로젝트의설정 → 지식 → 컨텍스트. 3단계에서 만든 메모리 파일이저장소 소스아래에 표시되고 활성화되어야 합니다. 만약생성로 표시된다면 해당 파일이 아직 연결된 브랜치에 도달하지 못한 것입니다.
다음을 참고하세요프로젝트 컨텍스트 설정및빌드 및 테스트 구성.
8단계: 조직 설정(선택 사항)
사용자에게 지금 이 중 어떤 설정을 적용할지 물어보세요. 모든 항목에는 적용 가능한 기본값이 있습니다:
- 멤버,설정 → 멤버: 풀 리퀘스트를 리뷰할 사람들로, 소유자, 관리자, 멤버 또는 리뷰어 역할을 맡습니다. 정책 및 제공업체 키를 변경해야 하는 사람에게만 관리자 권한을 부여하는 것을 권장합니다. Professional 요금제가 필요합니다.
- 공급자 키,설정 → 공급자 키: 조직 자체의 모델 제공업체 계정을 사용하기 위해서입니다. 사용자는 포털에 해당 키를 입력합니다. 제공업체 측에서 지출 한도가 설정된 제한된 권한의 키를 사용하는 것을 권장합니다.
- 다른 조직의 설정: 해당 조직에서 설정 번들을 내보낸 뒤설정 → 데이터 → 설정 내보내기. 비밀 정보는
플레이스홀더 형태로 전송되므로 모든
needsRebind항목은 미리보기에서 반드시 확인해야 합니다.
확인하세요계정 및 조직 생성, 공급자 키및설정 내보내기 및 가져오기.
9단계: Coroid에 직접 연결하기 (선택 사항)
클라이언트가 원격 MCP 서버를 지원하는 경우, 해당 MCP 서버를 통해 Coroid에
접속할 수 있습니다.https://api.coroid.ai/mcp. 설정 과정은 이에 의존하지 않지만, 이를 통해 직접 프로젝트를 확인하고 나중에 작업 실행을 도울 수 있습니다.
- 사용자는설정 → 연결 → Coroid MCP 서버
(
https://client.coroid.ai/settings/connections/coroid-mcp)입니다. 해당 조직에서 이용할 수 없다면 이 단계는 건너뛰세요. - 클라이언트 설정에서는 클라이언트별 명령어를 확인할 수 있습니다. OAuth를 사용하면 사용자가 브라우저에서 접근 권한을 승인합니다. 개인 액세스 토큰을 사용하는 경우에는 에서 생성합니다.액세스 토큰에서 환경변수로 저장하며, 본인의 셸에서 관리합니다. 값을 직접 확인할 필요는 없습니다.
- 작동에 필요한 최소한의 권한만 부여하는 것을 권장합니다:
mcp.read설정을 확인하고, 추가로mcp.work.write작업 생성 시에만 사용하세요. 토큰의 적용 범위를 해당 프로젝트로 제한하고, 만료일을 설정한 뒤자동화 정책를 설정한 뒤에 클라이언트가 무인으로 작업을 실행할 수 있습니다.
확인 방법:함수를list_projects, 그 다음get_project6단계의 각 프로젝트에 대해
실행하여 저장소와 브랜치를 확인하세요.
MCP용으로는 오직api.coroid.ai만 사용하세요. 클라이언트 포털의 호스트명으로는 이용할 수 없습니다.
확인하세요Coroid를 MCP 서버로 사용하기.
10단계: 첫 번째 작업 초안 작성하기
새로 만든 프로젝트 중 하나에서 사용자와 함께 작은 첫 번째 작업을 초안으로 작성하세요. 좋은 첫 번째 작업은 실제로 가능하고 규모가 작으며 기존 테스트와 연관되고 명확한 완료 기준을 갖춘 작업입니다. 인증, 결제, 데이터 마이그레이션, 무제한 정리 작업, 아직 결정되지 않은 디자인 관련 사항 등은 피하세요.
구현 방식이 아닌 결과물을 설명하세요: 작업이 완료되었을 때 어떤 상태가 되어야 하는지,
어떤 파일이 관련되는지, 건드리지 말아야 할 부분은 무엇인지 명시하세요. 사용자는
에서 이를 제출합니다.새 작업 (https://client.coroid.ai/work/new), 명세를 읽고 계획을 승인합니다. 작업 실행에는 에이전트 시간이 소요되며 무료 요금제에서는 UTC 기준 하루에 2시간만 제공되므로, 실행 시점은 사용자가 결정하도록 하세요.
확인하세요첫 번째 작업 실행하기및사양.
11단계: 인계하기
사용자에게 설정 기록을 전달하세요:
- 각 저장소, 해당 프로젝트, 저장소 모드 및 기본 브랜치
- 소스 제어의 연결 방식과 소유권 정보: 앱 설치 프로그램 또는 토큰 소유자 및 만료일
- 저장소별로 수정된 부분, 아직 처리되지 않은 부분(예: 열린 풀 리퀘스트와
AGENTS.md), 그리고 사용자가 별도로 남겨둔 부분 - 적용되거나 건너뛴 선택적 설정과 초안으로 작성된 첫 번째 작업
그런 다음 사용자를결과물을 리뷰하고 병합하기에서 첫 번째 pull request로 전달되는 내용을 확인하세요.
다음
계정 및 조직 생성하기— 동일한 설정을 수동으로 진행하는 방식입니다.