subagent의 역할, 초점, tool 접근 권한을 정의하는 재사용 가능한 페르소나 파일을 만드세요. subagent가 무엇을 확인하는지, 출력을 어떻게 형식화하는지, 무엇을 할 수 없는지를 정의합니다.

Agent 페르소나는 스폰된 subagent의 역할과 동작을 구성하는 markdown 파일입니다. 커스텀 모드가 메인 태스크의 동작 방식을 결정하는 반면, 페르소나는 도우미 subagent의 동작 방식을 결정합니다. subagent의 정체성, 체크리스트, 출력 형식, 제약 조건을 제어합니다.

페르소나의 동작 방식

Bob이 subagent를 스폰할 때 .bob/agents/에서 태스크와 일치하는 설명을 가진 페르소나 파일을 확인합니다. 파일이 발견되면 페르소나는 subagent의 모드로 로드됩니다. 역할 본문이 subagent의 시스템 프롬프트에 주입되고 기본 지시사항 위에 레이어로 쌓입니다.

페르소나는 메인 대화에 자동으로 로드되지 않습니다. Bob의 자체적인 판단이나 특정 태스크를 위임하도록 Bob에게 요청할 때 subagent가 스폰되는 경우에만 효과가 있습니다.

페르소나 파일 형식

페르소나 파일은 YAML 프론트 매터 뒤에 자유 형식의 역할 본문을 사용합니다.

---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
  - read
---

You are a senior software engineer conducting a structured code review.

Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic

Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.

Do not suggest fixes. Describe issues only.

프론트 매터 필드

필드	필수	타입	목적
`name`	예	string	로그에 사용되는 식별자. `.md`를 제외한 파일명과 일치해야 합니다.
`description`	예	string	Bob이 페르소나를 태스크에 매칭할 때 사용합니다. 한 줄 미션 선언문으로 작성하세요.
`tools`	아니오	list	subagent가 사용할 수 있는 tool 그룹을 제한합니다. 기본값을 상속받으려면 생략하세요.

Tool 그룹

tools 필드는 커스텀 모드와 동일한 그룹을 허용합니다: read, edit, command, browser, mcp.

리뷰어, 플래너, 요약자 같은 읽기 전용 페르소나의 경우 tools: [read]를 설정하여 실수로 편집되는 것을 방지하세요.

tools 필드는 상한선이지, 권한 부여가 아닙니다. 활성 태스크에 편집 권한이 활성화되어 있지 않으면 페르소나에 tools: [edit]를 설정해도 효과가 없습니다. 페르소나는 tool 접근을 제한할 수만 있으며, 태스크가 허용하는 범위를 초과하여 확장할 수 없습니다.

파일 위치

위치	범위	사용 사례
`<프로젝트>/.bob/agents/`	이 프로젝트만	리포지토리에 커밋된 팀 공유 페르소나
`~/.bob/agents/`	이 기기의 모든 프로젝트	모든 리포지토리에 걸쳐 적용되는 개인 페르소나

두 위치 모두 같은 이름의 페르소나를 포함하는 경우 프로젝트 수준 파일이 우선합니다.

.bob/ 디렉토리는 다른 구성과 함께 페르소나를 포함할 수 있습니다.

code-reviewer.md

pr-summarizer.md

custom_modes.yaml

첫 번째 페르소나 만들기

프로젝트 루트에 agents 디렉토리를 만드세요.

mkdir -p .bob/agents

페르소나 파일을 만드세요. 파일명(.md 제외)은 프론트 매터의 name 필드와 일치해야 합니다.

touch .bob/agents/code-reviewer.md

프론트 매터와 역할 본문을 추가하세요. 구조는 위의 페르소나 파일 형식을 참조하세요.

팀이 동일한 페르소나를 공유할 수 있도록 파일을 리포지토리에 커밋하세요.

페르소나 예시

code-reviewer.md

소스 파일의 정확성, 가독성, 유지보수성을 검토합니다. 심각도 순으로 정렬된 발견 사항 테이블을 생성하고 수정 사항을 제안하지 않습니다.

---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
  - read
---

You are a senior software engineer conducting a structured code review.

Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic

Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.

Do not suggest fixes. Describe issues only.
If a file has no findings, list it explicitly as clean.

pr-summarizer.md

변경된 파일 세트를 읽고 무엇이 바뀌었는지, 예상되는 의도, 리뷰어가 주의해야 할 영역을 담은 구조화된 pull request 설명을 생성합니다.

---
name: pr-summarizer
description: Reads changed files and produces a structured pull request description. Read-only.
tools:
  - read
---

You are a developer writing a pull request description for a teammate.

Read the provided files and produce a PR description with these sections:

**Summary**: One or two sentences describing what this change does.
**Why**: The likely motivation, inferred from the code changes.
**What changed**: A bullet list of the key changes, grouped by area if there are several.
**Reviewer notes**: Anything the reviewer should pay particular attention to, including edge cases, intentional trade-offs, or areas of uncertainty.

Write in plain, direct language. Do not pad the description.
Do not list every file changed. Focus on what matters to the reviewer.

페르소나 사용하기

Bob에게 태스크를 위임할 때 이름으로 페르소나를 참조하세요.

Use the code-reviewer persona to review the files in src/auth/.

Spawn a subagent using the pr-summarizer persona.
Read the changed files in this branch and produce a PR description.

Bob은 .bob/agents/에서 일치하는 페르소나를 로드하고 스폰된 subagent에 적용합니다.

인라인 페르소나

일회성 태스크의 경우 파일을 만들지 않고 프롬프트에 직접 역할을 설명할 수 있습니다.

Spawn an Explore subagent with this role:
You are a naming auditor. Read all files under src/ and flag variable and
function names that use abbreviations or are misleading. Return a table:
File, Line, Current Name, Issue.

인라인 역할은 단일 태스크에서 파일 기반 페르소나만큼 잘 작동합니다. 여러 태스크에서 동일한 역할을 재사용하거나 팀과 공유하려는 경우 페르소나 파일을 만드는 것이 좋습니다.

대화 기록 전달하기

기본적으로 subagent는 태스크 설명만 받습니다. 이전 대화 턴은 볼 수 없습니다. 이렇게 하면 컨텍스트가 작고 집중된 상태로 유지됩니다.

subagent가 대화의 이전 결정이나 제약 조건을 고려해야 하는 경우 이전 컨텍스트를 참조하는 프롬프트를 작성하세요.

Use the code-reviewer persona to review src/payments/.
Take into account what we discussed about the error handling approach.

Bob은 "what we discussed" 또는 "our earlier decision"과 같은 문구에서 fork_context: true를 추론하고 대화 기록을 subagent에 전달합니다.

참고:

대화 기록을 전달하면 전체 대화가 subagent의 context window에 복사됩니다. 긴 대화의 경우 상당한 토큰 비용이 추가됩니다. subagent가 이전 컨텍스트를 실제로 필요로 하지 않는 한 기본값(포크된 컨텍스트 없음)을 사용하세요.

페르소나, 모드, 규칙

메커니즘	범위	제어 대상	사용 시기
모드	전체 태스크	메인 태스크의 tool 상한선 및 역할 정의	메인 에이전트가 읽기 전용, docs 작성자, 보안 리뷰어 등 다른 자세가 필요한 경우
규칙	태스크 또는 모드	시스템 프롬프트에 로드되는 상시 지시사항	팀 관례, 형식 표준, 매번 적용되는 가드레일
페르소나	하나의 subagent	스폰된 subagent의 역할, 초점, 출력 형식, tool 제약 조건	도우미가 도메인 초점이 필요한 경우: 코드 리뷰, 변경 사항 요약, 테스트 계획

Agent 페르소나

이 페이지에서