요약(TL;DR): AI 에이전트에게 첫 작업을 할당할 때는 에이전트가 직접 검증할 수 있는 작은 작업을 고르고, 제목은 목표 결과 중심으로, 설명은 작업 범위와 '완료 조건'을 명시하여 작성하세요. 그런 다음 프롬프트로 일일이 지시하는 대신 작업을 위임하고 결과물을 검토하면 됩니다. Sharkly에서는 Claude Code나 Codex에 로그인된 Computer를 연결하고, 단일 역할을 가진 Agent를 생성한 뒤, Task를 만들어 담당자(Assignee)를 해당 Agent로 지정하면 됩니다. 담당자를 지정하는 즉시 실행이 시작되며, 완료된 결과는 Task로 반환되어 사람이 확인 후 완료(Done) 처리합니다.
지금까지 몇 주 동안 터미널에서 Claude Code나 Codex를 직접 사용해 보셨을 것입니다. 명령을 입력하면 코드를 수정하고, 지적하면 다시 수정하는 방식이었죠. 하지만 작업을 할당하는 것은 이와 완전히 다릅니다. 작업 내용을 한 번만 작성하여 넘겨준 뒤, 나중에 돌아와 결과를 확인하기만 하면 됩니다. 첫 시도는 대개 사소한 이유로 실패하곤 합니다. 작업 내용에 단순히 "로그인 버그 수정"이라고만 적혀 있거나, Computer의 코딩 도구에 로그인이 되어 있지 않거나, 에이전트가 직접 실행해 볼 수 있는 테스트가 없어 대충 짐작으로 끝내버리는 경우가 그렇습니다.
이 가이드에서는 AI 에이전트가 작업을 성공적으로 완수할 수 있도록 첫 작업을 할당하는 방법을 다룹니다. 적절한 작업을 선정하는 법, 작업 작성법, Sharkly에서의 구체적인 진행 절차, 그리고 반환된 결과물을 검토하는 방법까지 살펴봅니다. 특정 작업을 대화창(채팅)에서 진행할지 태스크로 할당할지 고민 중이라면 chat with an AI agent or assign a task? 글을 먼저 읽어보세요.
AI 에이전트가 끝까지 마칠 수 있는 첫 작업 고르기
AI 에이전트에게 작업을 할당한다는 것은 프롬프트로 일일이 이끌어가는 대신, 코딩 에이전트에게 문서화된 작업 단위를 맡겨 스스로 실행하게 한 뒤 그 결과를 검토하는 것을 의미합니다. 첫 작업은 일부러 아주 단순하고 사소한 것으로 잡으세요. 에이전트의 한계를 시험하는 것이 아니라 워크플로 환경이 제대로 갖춰졌는지 검증하는 단계이기 때문입니다.
적절한 첫 작업은 변경 사항(diff)을 한 문장으로 설명할 수 있을 만큼 작고, 에이전트가 직접 실행해 볼 수 있는 검증 수단이 있으며, 단일 모듈 내에 한정되고, 마이그레이션·운영 환경 설정·시크릿처럼 롤백하기 부담스러운 요소를 건드리지 않는 작업입니다.
| 적절한 첫 작업 | 부적절한 첫 작업 |
|---|---|
테스트를 포함하여 parseDate()에서 빈 문자열 및 잘못된 형식의 문자열 거부하기 |
날짜 처리 로직 정리하기 |
실패하는 test_invoice_totals를 수정하고 원인 설명하기 |
CI 고치기 |
list --json과 일치하도록 status에 --json 플래그 추가하기 |
CLI 개선하기 |
| 새 설정 파일에 맞게 README의 설치 단계 업데이트하기 | 문서 전면 개편하기 |
오른쪽 열의 작업들이 잘못된 일이라는 뜻은 아닙니다. 다만 경계가 모호하기 때문에 에이전트가 작업 범위를 임의로 정해야 하고, 목표를 달성했는지 여부도 사용자가 일일이 추측해야 합니다. Anthropic의 guide to working with Claude Code에서는 가장 중요한 핵심을 이렇게 언급합니다. "Claude에게 테스트, 빌드, 비교할 스크린샷 등 직접 실행해 볼 수 있는 검증 수단을 제공하세요." 검증 수단이 없는 에이전트는 완료했다고 말만 할 수 있을 뿐이지만, 검증 수단이 있는 에이전트는 결과를 직접 증명해 보일 수 있습니다.
AI 에이전트가 완료할 수 있도록 작업 작성하기
Sharkly의 Tasks documentation에서는 제목 작성 규칙을 다음과 같이 제시합니다. "유용한 제목은 주제가 아니라 결과를 명시해야 합니다." 그런 다음 본문 설명에는 새로운 팀원이나 Agent에게 필요한 내용, 즉 작업의 필요성, 포함/제외 범위, 관련 파일 및 예시, 이미 내려진 결정 사항, 완료 검토 기준 등을 담습니다. OpenAI의 Codex prompting guide에서도 거의 동일한 틀(목표, 맥락, 제약 조건, 완료 조건)을 권장합니다.
다음은 이러한 방식으로 작성된 첫 작업(Task SH-312)의 예시입니다.
Title: Reject empty and malformed strings in parseDate()
Why: Support tickets show a 500 when the import form gets a blank date.
Scope: src/dates/parse.ts and its tests only. Do not change callers.
Context: Follow the pattern in src/dates/format.ts.
Errors use InvalidInputError from src/errors.ts.
Constraints: No new dependencies. Keep the public signature.
Done when:
- parseDate("") and parseDate("31/02/2026") throw InvalidInputError
- npm test passes
- Your final comment lists the files you changed and the test command you ran
마지막 줄은 보기보다 훨씬 중요합니다. "작업을 마쳤습니다"라는 말을 10초 안에 직접 검증할 수 있는 확실한 증거로 바꿔주기 때문입니다.
작업 수가 늘어날 때 업무를 깔끔하게 유지해 주는 두 가지 습관이 있습니다. 변하지 않는 명확한 목표, 범위, 인수 기준은 댓글로 분산시키지 말고 설명(description) 본문에 작성하세요. 그리고 "요청이 모호할 때는 질문할 것"과 같은 일관된 기본 동작 규칙은 Agent의 instructions에 지정해 두어 각 Task에는 해당 작업에 특화된 내용만 들어가도록 하는 것입니다.
Sharkly에서 AI 에이전트에게 첫 작업 할당하기
이미 코딩 에이전트를 보유하고 있다면, Sharkly는 이들을 하나의 팀으로 만들어 줍니다. 첫 실행을 위해서는 작업 공간(Workspace), Computer, Agent, Task 네 가지가 필요합니다. 다음 단계는 Sharkly quickstart 가이드를 따릅니다.
- 로그인 및 워크스페이스 생성: app.sharkly.ai에서 이메일 인증 코드, Google 또는 GitHub 계정으로 로그인한 뒤 Organization을 생성합니다. Initialize workspace 단계에서 Software development를 선택하면 Sharkly가 Requirement 및 Bug 작업 유형이 포함된 Default Space를 생성합니다.
- Computer 연결: 실제 작업을 수행할 컴퓨터에 Claude Code, Codex, Gemini, OpenClaw, Hermes, Pi Agent 중 하나를 설치하고 로그인합니다. 데스크톱 앱을 사용하면 도구를 자동으로 감지하여 해당 컴퓨터를 등록합니다. 웹 환경에서는 Get started를 클릭한 뒤 Connect Computer를 선택하여 제공되는 명령어를 터미널에서 실행하면 됩니다. 공식 문서에서는 "온라인 상태는 연결이 유지되고 있음을 의미할 뿐"이라고 주의를 당부하므로, Computer 화면을 열어 Runtime이 Available 상태인지 확인하세요. 노트북과 서버 환경의 차이는 Computers in Sharkly에서 자세히 다룹니다.
- 단일 목적의 Agent 생성: Agents 메뉴를 열고 New Agent를 선택한 뒤 Code development를 고릅니다. 그다음 "the Agent automatically pulls Git repositories"를 선택하고 리포지토리를 추가합니다. 연결된 Computer를 선택하고 지침(instructions)은 간결하게 유지하세요. 각 Task가 독립된 worktree를 갖도록 작업 디렉터리는 Create temporary directory 상태로 두고, Agent가 안정적으로 작동하기 전까지는 가시성을 Personal로 유지합니다. 모델 선택 옵션은 별도로 없으므로, 특정 모델을 지정하려면 Custom arguments에 입력하세요.
- 읽기 전용 점검 실행: 코드를 수정하는 작업을 맡기기 전에, Repositories doc에서 권장하듯 "리포지토리를 살펴보고 주요 프로그래밍 언어, 패키지 매니저, 가장 적합한 테스트 명령어를 보고해 주세요. 파일은 수정하지 마세요."와 같은 Task를 먼저 실행해 보세요. 이를 통해 Agent가 리포지토리에 접근하고 Git 권한을 활용하며 명령어를 실행할 수 있는지 검증할 수 있습니다.
- Task 생성 및 할당: Tasks 페이지에서 New Task를 선택하고 앞서 작성한 제목과 설명을 붙여넣습니다. 새로 만든 Task는 기본적으로 Todo 상태가 됩니다. 여기서 Assignee를 해당 Agent로 지정하세요. 퀵스타트 문서에 나와 있듯이 "Assignee를 지정하는 즉시 Agent가 실행됩니다. 상태를 먼저 변경할 필요는 없습니다." 단, 대기 상태인 Backlog는 예외로, 다른 상태로 이동하기 전까지는 Task가 실행되지 않습니다.
AI 에이전트의 실행 과정 모니터링 및 결과 검토
실행(Run)은 Task의 상태와 별개로 고유한 상태값을 가집니다. Agent task execution 문서에서는 이를 다음과 같이 정의합니다.
| 실행 상태 | 의미 |
|---|---|
| Queued | 작업이 접수되어 디스패치 여유 용량을 기다리는 중 |
| Dispatched | 할당이 완료되어 Computer에서 실행을 시작하는 중 |
| Waiting for local directory | 설정된 지정 디렉터리 중 비어 있는 곳이 없음 |
| Running | Agent가 작업 수행 중 |
| Completed, Failed, Canceled | 실행 결과 |
해당 Task 화면의 Activity 탭에서는 Agent의 최종 결론을 포함한 댓글들을 확인할 수 있으며, Executions 탭에서는 실행 이력을 볼 수 있습니다. 사용자의 개입이 필요한 사항은 Inbox의 Primary 탭에 표시됩니다(답변이나 검토를 기다리는 대화, 실패하거나 차단된 작업, 직접 멘션된 알림 등).
실행이 완료되면 worktree 변경 사항을 검토한 후 유지, 머지 또는 폐기 여부를 결정합니다. 수정할 부분이 있다면 댓글에서 Agent를 @멘션하여 "빈 문자열 케이스에서 여전히 null을 반환하고 있습니다. InvalidInputError를 throw하도록 수정해 주세요."와 같이 구체적인 수정 사항을 전달하세요. 일반 댓글은 Agent를 시작시키지 않으며, @멘션을 해야만 실행됩니다. 결과물이 올바르다면 사람이 직접 Task를 Done으로 변경합니다. 탐색, 실행, 테스트, 보고는 Agent가 담당하지만, 방향 설정, 권한 부여, 최종 결과 승인은 사람의 몫입니다. 코드 변경 사항(diff)에서 중점적으로 살펴볼 부분은 reviewing AI-generated code with task-level evidence를 참고하세요.
단일 AI 에이전트, Crew, 아니면 터미널 작업?
키보드 앞에 앉아 당장 하나의 수정 사항만 신속하게 반영하고 싶다면, 터미널에서 직접 Claude Code나 Codex 세션을 실행하는 편이 작업 할당 프로세스보다 빠르며 이 경우에는 Sharkly가 필요하지 않습니다. 작업 할당 방식이 진가를 발휘하는 순간은 작업을 맡겨두고 자리를 비우고 싶을 때, 다른 팀원이 결과를 검토해야 할 때, 혹은 팀 전체가 확인할 수 있는 기록으로 남겨두어야 할 때입니다.
Sharkly 환경에서는 Crews documentation의 가이드라인을 따르는 것이 좋습니다. "작고 명확하게 정의된 작업은 단일 Agent에 직접 할당하세요. 리더 에이전트가 목표를 해석하고, 다른 Agent 멤버들을 참여시키며, 그 결과를 취합해야 하는 복합적인 작업에는 Crew를 활용하세요." 첫 작업은 단일 Agent에 할당하는 것이 바람직하며, 후자의 복합적인 시나리오는 Sharkly Crews에서 다룹니다.
단일 Agent가 특정 유형의 Task를 안정적으로 처리하게 되면, 퀵스타트 가이드의 조언처럼 더 전문화된 Agent로 분리하거나 반복되는 절차를 Skill로 저장할 수 있습니다. 그다음 단계는 일반적으로 여러 Task를 동시에 병렬로 처리하는 것입니다. 격리 환경 구성과 머지 순서에 관한 내용은 running multiple Claude Code agents in parallel 가이드를 확인하세요. 전체적인 연계 설정 방식은 Agents feature page에서 확인할 수 있습니다.
이미 구독 중인 코딩 에이전트에게 업무를 위임하고 그 모든 결과물을 한곳에서 취합해 확인하고 싶다면, Sharkly가 바로 그 문제를 해결하기 위해 설계된 도구입니다.
자주 묻는 질문(FAQ)
작업을 할당하면 AI 에이전트가 즉시 시작되나요? 대부분 그렇습니다. Task가 Backlog, Completed, Canceled, Duplicate 상태가 아니라면 Assignee를 지정하는 즉시 실행이 시작됩니다. 다만 Computer 사용 가능 여부, 동시 실행 제한, 디렉터리 여유 상황에 따라 Queued 상태로 대기할 수 있습니다.
Computer가 오프라인이 되면 어떻게 되나요? 새로운 실행은 컴퓨터가 다시 연결될 때까지 대기하며, 디스패치 전에 컴퓨터 연결이 끊기면 실행이 큐에 머무를 수 있습니다. 계속해서 작업을 수신해야 하는 노트북의 경우 '절전 모드 방지(Prevent sleep)'를 켜두세요.
Sharkly를 통해 모델 사용료를 결제하나요? 아닙니다. 실행 비용은 Computer에 이미 등록된 Claude Code, Codex 또는 API 플랜에 청구되며, Sharkly는 토큰을 판매하지 않습니다. Sharkly 자체는 현재 5인 이하 조직에 무료로 제공됩니다. 자세한 내용은 Sharkly pricing explained를 참고하세요.
에이전트가 내 컴퓨터의 어떤 항목에 접근할 수 있나요? Computer가 제공하는 모든 리소스, 즉 "Agent가 필요로 하는 운영체제, 파일, 인증 정보, 네트워크 접근 및 도구"에 접근할 수 있습니다. Agent와 Computer가 개인 인증 정보를 사용하는 동안에는 가시성을 Personal로 유지하고, Task 본문에 토큰을 절대 붙여넣지 마세요. 더 자세한 내용은 what an agent should and shouldn’t be allowed to do 문서를 확인하시기 바랍니다.
