레이어

레이어는 파이프라인을 구성하는 개별 단계 에이전트로, 각각 자체 하위 프로세스에서 고유한 프로바이더, 모델, 그리고 새로운 컨텍스트 윈도우를 가지고 실행됩니다. 레이어는 setting.json의 step 배열에 지정된 순서대로 실행됩니다. 각 레이어에서는 자유 텍스트 요약만 다음 레이어로 전달되며, 전체 대화 기록이나 도구 출력은 전달되지 않습니다.

레이어 파일 구조

step에 있는 각 이름은 .stepper/layer/<name>/index.md 경로에 레이어 파일을 가질 수 있습니다. 이 파일은 YAML frontmatter 블록(설정) 다음에 레이어의 시스템 프롬프트 본문이 이어지는 구조입니다.

---
description: implementation layer        # required
model: omlx/deepseek-coder               # or provider: + the default model
temperature: 0.2                         # sampling overrides → the request
top_p: 0.9
tools:
  allow: [read_file, write_file, edit_file, bash]
  deny:  [web_fetch]
permission:                              # per-layer overrides (tighten-only)
  Bash(rm *): deny
  Write(**): ask
mcp:
  allow: [context7]                      # which MCP servers this layer sees
skills: [rust-style]                     # skill bodies injected into the system prompt
steps: 40                                # step cap (ReAct iterations)
on-failure: skip                         # stop (default) | skip the layer and continue
retries: 1                               # extra attempts before applying on-failure
color: green
---
You are the implementation layer. Carry out the plan using the tools.

Frontmatter 필드

• description (필수) — 레이어의 역할에 대한 간략한 설명입니다.
• model 또는 provider — 이 레이어에서 기본 모델을 재정의합니다. provider/model-id 형식을 사용합니다(예: omlx/deepseek-coder).
• temperature 및 top_p — API 요청에 전달되는 샘플링 파라미터입니다.
• tools.allow 및 tools.deny — 이 레이어가 호출할 수 있는 도구(예: read_file, write_file, bash)를 제어합니다.
• permission — 전역 규칙과 병합되는 레이어별 권한 규칙으로, 제한을 강화할 수만 있습니다(아래 섹션 참조).
• mcp.allow — 이 레이어가 접근할 수 있는 MCP 서버 목록입니다(예: [context7]).
• skills — 이 레이어에서 사용할 수 있는 스킬 이름의 배열로, 본문은 필요할 때 지연 로드됩니다.
• steps — 레이어가 중단되기 전까지의 최대 ReAct 반복 횟수입니다.
• on-failure — stop(기본값; 파이프라인 중단) 또는 skip(다음 레이어로 계속) 중 하나입니다.
• retries — on-failure가 적용되기 전 추가로 시도하는 횟수입니다.
• color — 레이어에 대한 선택적 TUI 색상 레이블입니다.

권한 강화

레이어별 permission 규칙은 전역 규칙 위에 병합되며 deny > ask > allow 해결 순서를 따릅니다. 즉, 레이어는 제한을 **강화**할 수만 있으며, 기본 deny 규칙을 완화할 수는 없습니다. 예를 들어 전역 설정이 Bash(rm *)를 거부하는 경우 레이어가 이를 허용할 수는 없지만, 전역적으로 허용된 도구에 대해 레이어가 확인을 요청하도록 만들 수는 있습니다.

병렬 레이어(팬아웃)

레이어는 팬아웃으로 실행될 수 있습니다. 하위 작업당 하나의 동시 워커가 각각 자체적인 새로운 컨텍스트 윈도우와 동일한 레이어 구성을 가지고 실행되며, 다음 레이어가 결과를 처리하기 전에 모두 합쳐집니다. 병렬 실행을 활성화하려면 레이어에 parallel: true를 표시합니다.

작업 할당

병렬 레이어 **바로 앞** 레이어에는 assign_tasks 도구가 제공됩니다. 이 레이어는 assign_tasks({ tasks: [{label, prompt}, …] })를 호출하여 작업을 하위 작업으로 나눕니다. 각 하위 작업은 병렬 레이어의 하나의 워커가 됩니다. 앞 레이어가 작업을 할당하지 않으면 병렬 레이어는 작업 컨텍스트 없이 한 번만 실행됩니다.

동시성과 워커 패널

parallel-max를 사용하면 동시에 실행되는 워커 수를 제한할 수 있습니다(예: parallel-max: 4). 이는 동시성을 제한할 뿐 작업을 버리지는 않습니다. 작업은 대기열에 들어가고 워커가 끝나는 대로 실행됩니다. TUI는 워커마다 한 행을 보여주는 실시간 **워커 패널**을 표시하며, 현재 상태, 마지막으로 호출한 도구, 토큰 수를 보여줍니다. 모든 워커가 끝나면 각 요약이 다음 레이어를 위한 단일 핸드오프로 수렴됩니다.

---
description: implementation layer
parallel: true            # fan out — one worker per assigned subtask
parallel-max: 4           # max workers running AT ONCE (concurrency cap; no task is dropped)
model: omlx/deepseek-coder
tools:
  allow: [read_file, write_file, edit_file, bash]
---
You are one implementation worker. Complete only your assigned subtask, then
end with a concise summary of what you changed.

워크플로 예시

step: ["plan", "implement", "test"]에서 implement에 parallel:이 표시된 경우, plan 레이어는 요약을 출력하고 assign_tasks를 호출하여 작업을 구현 하위 작업으로 나눕니다. 각 하위 작업은 전체 레이어 구성을 가진 하나의 implement 워커를 생성합니다. 모든 워커가 완료되면 test는 모든 워커 변경 사항이 병합된 요약을 받습니다. 모델이 호출할 수 있는 dispatch 도구(dispatch.enabled: true인 경우)는 서브에이전트에 동일한 워커 패널을 사용합니다.