문서

AI 어시스턴트를 이용한 설정 방법

이 런북은 코딩 어시스턴트가 저장소를 준비하고, CoRoid에 필요한 액세스 권한을 설정하며, 각 프로젝트가 빌드 및 테스트 가능한지 확인하는 데 따르는 절차를 안내합니다.

이 페이지는 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 소프트웨어 팩토리입니다. 프로젝트가 설정되면 회사 내 누구나 자연어로 작업 내용을 기술할 수 있으며, CoRoid는 프로젝트 표준에 맞게 해당 작업을 빌드, 테스트 및 검토한 뒤 사용자의 저장소에 pull request를 생성합니다. 다음 규칙을 반드시 준수하세요:

  1. 사용자가 행동하고, 어시스턴트가 준비합니다.사용자를 대신해 가입, 로그인, 약관 동의, 앱 설치 또는 접근 권한 부여 작업은 할 수 없습니다. 정확히 어떤 작업을 어디서 해야 하는지 알려주고, 사용자가 완료를 확인할 때까지 기다리세요.
  2. 대화 내용에 비밀 정보를 포함하지 마세요.절대 안 합니다. 비밀번호, 개인 액세스 토큰, 제공업체 키 또는 MCP 토큰을 요청하지 마세요. 사용자는 CoRoid 포털이나 자신의 셸에 직접 비밀번호를 입력합니다. 만약 채팅창에 이러한 정보가 붙여넣어진 경우, 사용자에게 해당 토큰을 취소하고 새로 발급받도록 알려주세요.
  3. 변경 사항이 발생하기 전에 항상 확인하세요: 사용자의 저장소에 있는 커밋, 브랜치 및 풀 리퀘스트, CoRoid 프로젝트, 그리고 초대장.
  4. 다음 단계로 넘어가기 전에 각 단계를 확인하세요.검사에 실패할 경우 해당 단계의 안내를 따르고, 통과하거나 사용자가 건너뛰기로 결정할 때만 다음 단계로 진행하세요.
  5. 제품의 기능을 따르고, 임의의 추측은 하지 마세요.포털에 이 실행 가이드에 설명되지 않은 항목이 표시될 경우, 사용자에게 보이는 내용을 알려주고 포털의 안내를 따르세요. 설정을 임의로 만들어내지 마세요.
  6. 설정 기록을 보관하세요각 단계와 그 결과를 끝까지 기록해 두세요.

각 단계는 세부 정보가 담긴 페이지와 연결됩니다.https://coroid.ai/llms.txt전체 문서를 색인화합니다.

단계 1: 계획을 합의하세요

다음 질문들을 한 번에 묻되, 따로따로 묻지 마세요:

질문중요성
CoRoid가 작업할 저장소는 어떤 것들인가요?저장소당 하나의 프로젝트를 설정하세요.
GitHub 또는 GitLab? 개인 소유인가요, 아니면 조직 소유인가요?CoRoid의 연결 방식과 승인 담당자를 결정합니다.
CoRoid가 풀 리퀘스트를 생성해야 합니까(동기화됨), 아니면 처음에는 작업을 CoRoid 내부에만 유지해야 합니까(로컬 전용)?로컬 전용 모드는 저장소에 절대 기록하지 않습니다.
기존에 CoRoid 조직이 존재하며, 어떤 요금제를 사용 중인가요?무료 요금제는 프로젝트 하나만 지원하며 다른 멤버는 추가할 수 없습니다.
누가 작업을 검토하며, 어떤 역할을 맡나요?멤버를 초대하려면 Professional 요금제가 필요합니다.
CoRoid가 조직 자체의 모델 제공업체 키를 사용해야 합니까?선택 사항입니다. CoRoid가 라우팅하는 모델에는 이 키가 필요하지 않습니다.

그런 다음 아래의 단계들, 사용자가 개입해야 하는 부분 및 적용 대상 저장소를 포함하여 계획을 다시 한번 확인해 주세요.

다음을 참조하세요:요금제 및 가격, 사용 제한 및 할당량및동기화 또는 로컬 전용.

단계 2: 각 저장소가 깨끗한 클론 상태에서 빌드 및 테스트되는지 확인하세요

이것은 가장 유용한 작업입니다. 모든 CoRoid 작업은 깨끗하고 일회용인 Linux 워크스페이스에서 실행됩니다. 즉, 새로운 클론을 사용하며 캐시된 데이터나 추가로 설치된 도구는 없고 이미지에 포함된 툴체인만 사용합니다. 프로젝트를 빌드 및 테스트할 수 없는 에이전트는 자신의 작업을 검증할 수 없으며, 변경 사항과 무관한 이유로 작업이 검증 단계에서 실패하게 됩니다.

사용자가 해당 저장소에서 로컬로 작업할 수 있다면, 각 저장소에 대해 다음을 수행하세요:

  1. 사용 언어, 패키지 관리자 및 모노레포 여부를 확인하세요.
  2. README, CI 설정 및 매니페스트 파일에서 설치, 빌드 및 테스트 명령어를 찾으세요.
  3. 실행하기 전에 항상 확인하세요. 그런 다음 빈 임시 디렉터리에 저장소를 클론한 뒤, 다른 설정 없이 설치, 빌드 및 테스트를 진행하세요. 사용자의 작업 복사본에는 캐시 및.env파일이 있어 문제를 숨길 수 있습니다.
  4. 새로운 클론에서는 없지만 실행에 필요한 모든 항목을 기록하세요:
    • 테스트에서 요구하는 서비스: 데이터베이스, 캐시 또는 큐 등
    • 테스트 전에 필요한 단계: 코드 생성, 마이그레이션 또는 피시처 생성 등
    • 환경 변수 또는.env파일로, 커밋되지 않은 항목
    • 개인용 패키지 레지스트리
    • 이미지에 포함되지 않은 런타임 에이전트 환경

공유 환경에 배포하거나 게시하거나 접근하는 명령어는 절대 실행하지 마세요. 테스트 스위트가 느리거나 유료 서비스를 호출하는 경우에는 먼저 사용자에게 확인하세요.

각 저장소별로 간단한 준비 상태 점검 결과를 보고해 주세요: 사용된 명령어, 테스트 스위트 실행에 걸린 시간, 통과한 항목, 그리고 제안된 수정 방안이 포함된 각 차이점을 포함합니다.

차이점제안할 수정 방안
테스트에는 데이터베이스나 다른 서비스가 필요합니다.테스트 스위트와 해당 서비스를 실행하는 Dockerfile 또는 Compose 파일입니다.
필수적인.env파일이 커밋되지 않았습니다.코드 내에 테스트 기본 설정을 정의하거나, 비밀 값이 아닌 내용으로 구성된 커밋된 테스트 설정 파일을 사용하세요.
테스트에는 실제 비밀 값이 필요합니다.테스트에서 해당 종속성을 모의 처리하세요. 비밀 값은 절대 커밋하지 마세요.
종속성은 프라이빗 레지스트리에서 가져옵니다.사용자에게 알려주세요. CoRoid는 프로젝트 구성을 위해 해당 정보에 대한 인증 정보가 필요합니다.
명령어는 하위 디렉터리에서만 작동합니다.정확한 디렉터리와 워크스페이스 필터를 기록해 주세요.

누락된 런타임도 장애 요인이 되지 않습니다. 도구 체인을 포함하는 컨테이너를 사용하면 해결됩니다. 로컬에서 저장소에 접근할 수 없는 경우에는 사용자로부터 가능한 정보를 수집하고, 클린 클론 점검이 이루어지지 않았음을 기록해 주세요.

다음을 참조하세요:빌드 및 테스트 설정그리고언어 지원 및 에이전트 환경.

3단계: CoRoid의 에이전트가 읽는 지침 작성하기

모든 작업 전에 CoRoid의 에이전트는 저장소에 있는 메모리 파일을 읽습니다:AGENTS.md, CLAUDE.md또는GEMINI.md루트 디렉터리에 위치하며, Cursor의 규칙은.cursor/rules. 2단계에서 검증한 명령어는 여기에 포함됩니다.

다음을 제안하세요:AGENTS.md, 또는 기존 문서에 추가하여 다음 내용을 포함하세요:

  • 클린 클론에서 검증된 설치, 빌드 및 테스트 명령어와 이를 실행할 디렉터리입니다.
  • 테스트에 필요한 단계와 서비스입니다.
  • 하나의 패키지나 파일과 같이 가장 좁은 범위의 유용한 테스트 세트를 실행하는 방법입니다.
  • 코드에 명시되지 않은 관례와 경계: 고정된 모듈, 수정하면 안 되는 영역, 추가하면 안 되는 종속성 등입니다.

코드에 이미 명시된 내용은 제외하고 파일 크기를 줄이세요. 만약CLAUDE.md또는.cursor/rules에 동일한 지침이 포함되어 있다면, 이를AGENTS.md에 한 번만 기재하고 다른 파일에서는@AGENTS.md줄을 사용하여 가져오세요. 로컬 Git 워크플로우에 관한 내용이라면 다음을 참조하세요:모든 에이전트에 대해 AGENTS.md를 적용하세요..

변경 사항을 사용자에게 보여주세요. 사용자의 승인을 얻으면 새 브랜치에 커밋하고 pull request를 열거나, 사용자가 직접 커밋하도록 남겨두세요. 첫 번째 작업이 시작되기 전에 이 변경 사항이 기본 브랜치에 반영되어야 합니다. 왜냐하면 각 작업은 해당 브랜치의 체크아웃본에서 메모리 파일을 읽기 때문입니다. 사용자가 승인한 2단계의 수정 사항도 같은 방식으로 처리하세요.

다음을 참조하세요:프로젝트 컨텍스트 설정그리고프로젝트 컨텍스트.

4단계: 계정 및 조직(사용자)

사용자가 이미 CoRoid 조직의 소유자 또는 관리자로 속해 있다면 이 단계는 건너뛰세요.

사용자에게 다음을 요청하세요:

  1. 에서 가입하도록 안내하세요.https://client.coroid.ai/auth/signup업무용 이메일을 사용하여 가입하고 주소를 인증하세요.
  2. 이용 약관에 동의하세요.
  3. 조직을 생성하세요.

확인 사항:사용자가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) 그리고 각 저장소별로:

  1. 연결된 제공업체에서 저장소를 선택하거나URL로 연결를 이용해 공개 저장소를 추가할 수 있습니다
  2. 를 선택합니다저장소 모드: CoRoid가 브랜치를 푸시하고 풀 리퀘스트를 생성하는 '동기화' 모드, 또는 누군가 선택하기 전까지는 저장소에 절대 쓰지 않는 '로컬 전용' 모드.동기화 시작
  3. 기본 브랜치를 확인합니다
  4. 프로젝트를 생성합니다

만약 팀에서 기본 브랜치가 아닌 다른 브랜치로 병합한다면, 예컨대develop와 같이, 프로젝트의 저장소 설정에서 기본 브랜치를 지정해 주세요. 잘못된 기본 브랜치 설정 시 풀 요청이 아무도 검토하지 않는 브랜치로 전송됩니다.

만약 목록에 저장소가 표시되지 않는다면, 원인은 거의 다음 중 하나입니다:

  • GitHub 앱에 해당 저장소에 대한 접근 권한이 부여되지 않았습니다
  • 토큰의 범위가 좁아 저장소 목록을 조회할 수 없습니다
  • 저장소가 연결된 조직과 다른 조직에 속해 있습니다

다음을 참고하세요첫 번째 프로젝트 만들기와저장소 및 브랜치 설정.

7단계: CoRoid가 찾은 내용 확인하기

사용자에게 각 프로젝트의 개요 페이지를 열어서저장소상세 정보와설정 완료:

  • 상태와브랜치: 저장소가 클론되어 합의한 기본 브랜치에 위치합니다. 만약 개요에 저장소가 아직 클론되지 않았다고 표시된다면, 사용자는저장소 클론.
  • 스택: CoRoid가 감지한 언어, 프레임워크, 패키지 관리자 및 테스트 도구입니다. 이를 준비 상태 확인 결과와 비교해 보세요. 첫 동기화 후에 스택이 비어 있거나 잘못된 경우, 사용자는 거기서부터 다시 스캔할 수 있습니다.
  • 설정 완료: "종속성 설치가 제대로 이루어지지 않았습니다"와 같은 항목은 2단계에서 발견된 문제점과 동일합니다. 사용자와 함께 이 문제를 해결해 주세요.

그런 다음 사용자는 프로젝트의설정 → 지식 → 컨텍스트로 이동합니다. 3단계에서 생성된 메모리 파일이저장소 소스항목에 포함되어 활성화되어 있어야 합니다. 만약생성가 표시된다면, 해당 파일이 아직 연결된 브랜치에 도달하지 못한 것입니다.

다음을 참고하세요프로젝트 컨텍스트 설정와빌드 및 테스트 구성.

8단계: 조직 설정(선택 사항)

사용자에게 현재 이러한 설정을 적용할지 물어보세요. 모든 설정에는 적용 가능한 기본값이 있습니다:

  • 멤버,설정 → 멤버: 풀 요청을 리뷰할 사람들로, 소유자, 관리자, 멤버 또는 리뷰어 역할을 가집니다. 정책 및 제공업체 키를 변경해야 하는 사람에게는 관리자 권한만 부여할 것을 권장합니다. Professional 플랜이 필요합니다.
  • 공급자 키,설정 → 공급자 키: 조직 자체의 모델 제공업체 계정을 사용하기 위해서입니다. 사용자는 포털에 해당 키를 입력합니다. 제공업체 측에서 지출 한도가 설정된 제한된 권한의 키를 사용할 것을 권장합니다.
  • 다른 조직의 설정: 해당 위치에 설정 번들을 내보내고 그곳에서 가져오세요설정 → 데이터 → 설정 내보내기. 비밀 정보는 플레이스홀더 형태로 전송되므로 모든needsRebind항목을 미리보기에서 반드시 확인해야 합니다.

다음을 참조하세요계정 및 조직 생성하기, 공급자 키그리고설정 내보내기 및 가져오기.

9단계: CoRoid에 직접 연결하기 (선택 사항)

사용 중인 클라이언트가 원격 MCP 서버를 지원한다면, CoRoid의 MCP 서버를 통해 접속할 수 있습니다.https://api.coroid.ai/mcp. 설정 과정은 이에 의존하지 않지만, 이를 통해 직접 프로젝트를 확인하고 나중에 작업 실행을 도울 수 있습니다.

  1. 사용자는설정 → 연결 → CoRoid MCP 서버 (https://client.coroid.ai/settings/connections/coroid-mcp). 해당 조직에서 사용할 수 없는 경우 이 단계는 건너뛰세요.
  2. 클라이언트 설정에는 클라이언트별 명령어가 표시됩니다. OAuth를 사용하면 사용자가 브라우저에서 접근 권한을 승인합니다. 개인 액세스 토큰을 사용하는 경우, 설정에서 생성합니다.액세스 토큰그리고 자신의 셸에 환경 변수로 저장합니다. 값을 직접 확인할 필요는 없습니다.
  3. 작동하는 최소한의 접근 권한을 권장합니다: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로 생성된 내용을 확인하세요.

다음

계정 및 조직 생성하기— 동일한 설정을 수동으로 진행한 경우입니다.