본문으로 건너뛰기

레이아웃 시스템 가이드

CrewX의 레이아웃 시스템을 사용하여 재사용 가능하고 사용자 정의할 수 있는 프롬프트 템플릿을 만드는 방법에 대한 완벽한 가이드입니다.

목차​

개요​

CrewX 레이아웃은 에이전트 간에 공유할 수 있는 재사용 가능한 프롬프트 구조 템플릿을 만드는 방법을 제공합니다. 레이아웃을 AI 프롬프트의 React 컴포넌트로 생각해보세요. 구조를 정의하고 사용자 정의 가능한 props를 수용합니다.

레이아웃이란 무엇인가요?​

레이아웃은 프롬프트 구조 (컨테이너)를 프롬프트 콘텐츠 (실제 지시사항)와 분리합니다:

측면레이아웃 (inline.layout)프롬프트 (inline.prompt)
목적구조 템플릿 정의에이전트별 지시사항 포함
재사용성여러 에이전트 간 공유각 에이전트에 고유함
사용자 정의Props (React PropTypes처럼)직접 텍스트 콘텐츠
예제보안 컨테이너, 문서 섹션"당신은 코드 리뷰어입니다..."

왜 레이아웃을 사용하나요?​

레이아웃 없이:

agents:
  - id: agent1
    inline:
      prompt: |
        <crewx_system_prompt>
        {{{documents.manual.content}}}
        </crewx_system_prompt>
        <system_prompt key="{{vars.security_key}}">
        You are agent 1...
        </system_prompt>

  - id: agent2
    inline:
      prompt: |
        <crewx_system_prompt>
        {{{documents.manual.content}}}  # 중복된 구조
        </crewx_system_prompt>
        <system_prompt key="{{vars.security_key}}">
        You are agent 2...
        </system_prompt>

레이아웃 사용:

agents:
  - id: agent1
    inline:
      layout: "crewx/default"  # 재사용 가능한 구조
      prompt: |
        You are agent 1...

  - id: agent2
    inline:
      layout: "crewx/default"  # 같은 구조, 다른 콘텐츠
      prompt: |
        You are agent 2...

빠른 시작​

단계 1: 레이아웃 선택​

내장 레이아웃으로 시작하세요:

agents:
  - id: my_agent
    inline:
      layout: "crewx/default"  # 간단한 문자열 참조
      prompt: |
        You are a helpful assistant.

단계 2: 최소 레이아웃 사용​

전체 에이전트 프로필이 없는 간단한 에이전트의 경우:

agents:
  - id: simple_agent
    inline:
      layout: "crewx/minimal"  # 가벼운 래퍼
      prompt: |
        You are a simple assistant.

단계 3: 에이전트 테스트​

crewx query "@simple_agent help me with my task"

이제 레이아웃을 사용하고 있습니다!

기본 사용법​

내장 레이아웃 사용​

레이아웃 ID로 참조하세요:

agents:
  - id: simple_agent
    inline:
      layout: "crewx/default"  # 문자열 형식
      prompt: |
        Your instructions here.

사용 가능한 내장 레이아웃:

  • crewx/default - 보안 컨테이너가 있는 전체 에이전트 프로필 (기본값)
  • crewx/minimal - 최소 보안 래퍼만 (가벼움)

레이아웃 선택​

사용 사례에 맞는 적절한 레이아웃을 선택하세요:

agents:
  - id: full_agent
    inline:
      layout: "crewx/default"  # 전체 에이전트 프로필
      prompt: |
        You are a complex agent with full capabilities.

  - id: minimal_agent
    inline:
      layout: "crewx/minimal"  # 최소 래퍼만
      prompt: |
        You are a simple, focused agent.

기본 동작​

layout을 생략하면 CrewX가 자동으로 crewx/default를 사용합니다:

agents:
  - id: my_agent
    inline:
      # 레이아웃을 지정하지 않음 → crewx/default 사용
      prompt: |
        Your instructions here.

내장 레이아웃​

crewx/default​

별도로 지정하지 않는 한 모든 에이전트가 사용하는 표준 레이아웃입니다. 전체 에이전트 프로필과 완벽한 컨텍스트를 제공합니다.

구조:

  • 프롬프트를 <crewx_system_prompt>와 <system_prompt> 보안 컨테이너에 래핑
  • 전체 에이전트 프로필 포함 (신원, CLI 옵션, 세션 정보)
  • CrewX 사용자 설명서 문서 포함
  • 에이전트의 inline.prompt를 보안 컨테이너에 주입

Props: 없음

사용법:

agents:
  - id: my_agent
    inline:
      layout: "crewx/default"  # 명시적 (또는 기본값으로 생략)
      prompt: |
        You are a helpful assistant.

언제 사용하나요:

  • 전체 컨텍스트와 기능이 필요한 표준 에이전트
  • 완벽한 에이전트 프로필 정보의 이점을 받을 수 있는 에이전트
  • 대부분의 사용 사례에 기본값

crewx/minimal​

전체 에이전트 프로필 없이 필수 보안 래퍼만 제공하는 가벼운 레이아웃입니다.

구조:

  • 프롬프트를 <crewx_system_prompt>와 <system_prompt> 보안 컨테이너에 래핑
  • 에이전트의 inline.prompt를 직접 주입 (추가 컨텍스트 없음)
  • 간단한 에이전트를 위한 최소 오버헤드

Props: 없음

사용법:

agents:
  - id: simple_agent
    inline:
      layout: "crewx/minimal"  # 가벼운 래퍼
      prompt: |
        You are a simple assistant.

언제 사용하나요:

  • 명확하고 특정 작업에 집중하는 간단한 에이전트
  • 최소한의 시스템 컨텍스트를 원할 때
  • 토큰 사용을 최소화하려는 성능 민감한 시나리오
  • 전체 에이전트 프로필 정보가 필요하지 않은 에이전트

사용자 정의 레이아웃 만들기​

crewx.yaml 파일에서 사용자 정의 레이아웃을 정의하여 재사용 가능한 프롬프트 구조를 만들 수 있습니다.

기본 사용자 정의 레이아웃​

crewx.yaml의 layouts 섹션에서 레이아웃을 정의하세요:

# crewx.yaml
layouts:
  my_custom_layout: |
    <system_prompt key="{{vars.security_key}}">
    You are a specialized agent.

    {{{agent.inline.prompt}}}

    Always follow best practices.
    </system_prompt>

agents:
  - id: my_agent
    inline:
      layout: "my_custom_layout"  # 사용자 정의 레이아웃 참조
      prompt: |
        You are a code reviewer focusing on security.

단순 매개변수화된 레이아웃​

여러 에이전트에서 공유되는 레이아웃의 경우 프롬프트에 직접 매개변수를 포함하세요:

# crewx.yaml
layouts:
  team_layout: |
    <system_prompt key="{{vars.security_key}}">
    You are a specialized team member.

    {{{agent.inline.prompt}}}

    Always collaborate with your team and follow best practices.
    </system_prompt>

agents:
  - id: frontend_dev
    inline:
      layout: "team_layout"
      prompt: |
        You are a member of the Frontend Team.
        Your focus area: frontend
        You specialize in React and TypeScript.

  - id: backend_dev
    inline:
      layout: "team_layout"
      prompt: |
        You are a member of the Backend Team.
        Your focus area: backend
        You specialize in Node.js and databases.

참고: 대부분의 경우 prompt 필드에 직접 매개변수를 포함하는 것이 props 검증을 사용하는 것보다 더 간단하고 유지 관리하기 쉽습니다.

고급: Props 검증이 있는 레이아웃​

유형 검증과 기본값이 필요한 고급 사용 사례의 경우 propsSchema를 사용하세요:

# crewx.yaml
layouts:
  config_layout:
    propsSchema:
      teamName:
        type: string
        defaultValue: "Development Team"
      maxContextDocs:
        type: number
        min: 1
        max: 50
        defaultValue: 10
      verbose:
        type: bool
        defaultValue: false
    template: |
      <system_prompt key="{{vars.security_key}}">
      <team>{{props.teamName}}</team>
      <context_limit>{{props.maxContextDocs}}</context_limit>
      <verbose_mode>{{props.verbose}}</verbose_mode>

      {{{agent.inline.prompt}}}

      Follow team guidelines and best practices.
      </system_prompt>

agents:
  # 기본 props가 있는 에이전트
  - id: default_agent
    inline:
      layout: "config_layout"  # 기본값 사용
      prompt: |
        You are an agent with default settings.

  # 사용자 정의 props가 있는 에이전트
  - id: custom_agent
    inline:
      layout:
        id: "config_layout"
        props:
          teamName: "AI Research Team"
          maxContextDocs: 25
          verbose: true
      prompt: |
        You are an agent with custom settings.

Props 검증을 언제 사용하나요:

  • 여러 에이전트가 다른 구성 값이 필요할 때
  • 유형 안전성이 중요할 때 (숫자 범위, 열거형, 부울)
  • 잘못된 값에 대해 검증 오류를 원할 때
  • 다양한 설정이 있는 많은 에이전트에서 공유하는 레이아웃

사용 가능한 템플릿 변수​

사용자 정의 레이아웃에서 이러한 변수를 사용하세요:

  • {{{agent.inline.prompt}}} - 에이전트의 프롬프트 콘텐츠
  • {{{agent.id}}}, {{{agent.name}}} - 에이전트 메타데이터
  • {{vars.security_key}} - 컨테이너용 보안 키
  • {{{documents.doc-name.content}}} - 문서 콘텐츠
  • {{props.yourPropName}} - 사용자 정의 props
  • {{env.YOUR_ENV_VAR}} - 환경 변수

레이아웃 모범 사례​

  1. 항상 보안 컨테이너 사용: <system_prompt key="{{vars.security_key}}">에 콘텐츠를 래핑하세요
  2. 에이전트 프롬프트 주입: 삼중 괄호로 {{{agent.inline.prompt}}}를 사용하세요
  3. 기본값 제공: 모든 props에 대해 defaultValue 설정
  4. 간단하게 유지: 최소 구조로 시작하여 필요할 때만 복잡성 추가
  5. 일반적인 패턴 재사용: 반복되는 구조를 레이아웃으로 추출

예제: 문서 중심 레이아웃​

layouts:
  doc_reviewer_layout: |
    <system_prompt key="{{vars.security_key}}">
    <role>Documentation Reviewer</role>

    <standards>
    {{{documents.writing-guide.content}}}
    </standards>

    <instructions>
    {{{agent.inline.prompt}}}
    </instructions>

    Always check for clarity, accuracy, and consistency.
    </system_prompt>

documents:
  writing-guide: |
    # Writing Guide
    - Use clear, concise language
    - Include code examples
    - Follow markdown conventions

agents:
  - id: doc_reviewer
    inline:
      layout: "doc_reviewer_layout"
      prompt: |
        Review documentation for technical accuracy and readability.

Props 스키마​

참고: 내장 레이아웃 (crewx/default와 crewx/minimal)은 props를 사용하지 않습니다. 이 섹션은 사용자 정의 레이아웃을 만들 때 관련이 있습니다.

CrewX는 레이아웃 props에 대해 React PropTypes 스타일 검증을 사용합니다. React에 익숙하다면 자연스러울 것입니다.

Prop 유형​

문자열 Props​

propsSchema:
  name:
    type: string
    defaultValue: "default"

제약 포함:

propsSchema:
  theme:
    type: string
    oneOf: ["light", "dark", "auto"]  # 열거형 값
    defaultValue: "auto"

사용자 정의 레이아웃에서 사용:

layout:
  id: "my/custom-layout"
  props:
    theme: "dark"  # "light", "dark" 또는 "auto"이어야 함

숫자 Props​

propsSchema:
  maxItems:
    type: number
    min: 1
    max: 100
    defaultValue: 10

사용자 정의 레이아웃에서 사용:

layout:
  id: "my/custom-layout"
  props:
    maxItems: 25  # 1과 100 사이여야 함

부울 Props​

propsSchema:
  enabled:
    type: bool
    defaultValue: true

사용자 정의 레이아웃에서 사용:

layout:
  id: "my/custom-layout"
  props:
    enabled: false

배열 Props​

단순 배열:

propsSchema:
  tags:
    type: array
    defaultValue: []

입력된 배열 (arrayOf):

propsSchema:
  sections:
    type: arrayOf
    itemType: string
    itemOneOf: ["section1", "section2", "section3"]
    defaultValue: ["section1"]

사용자 정의 레이아웃에서 사용:

layout:
  id: "my/custom-layout"
  props:
    sections: ["section1", "section2"]  # 각 항목이 유효해야 함

필수 Props​

isRequired를 사용하여 필수 props를 적용하세요:

propsSchema:
  userId:
    type: string
    isRequired: true  # 반드시 제공해야 함

사용자 정의 레이아웃에서 사용:

layout:
  id: "my/custom-layout"
  props:
    userId: "user123"  # 필수, 생략 불가

복잡한 예제​

propsSchema:
  # 열거형 제약이 있는 문자열
  theme:
    type: string
    oneOf: ["light", "dark", "auto"]
    defaultValue: "auto"
    description: "UI theme preference"

  # 범위 제약이 있는 숫자
  maxDocs:
    type: number
    min: 1
    max: 50
    defaultValue: 10
    description: "Maximum documents to load"

  # 부울 플래그
  enableCache:
    type: bool
    defaultValue: true
    description: "Enable response caching"

  # 특정 문자열 배열
  features:
    type: arrayOf
    itemType: string
    itemOneOf: ["search", "analytics", "reporting"]
    defaultValue: ["search"]
    description: "Enabled features"

  # 필수 문자열
  agentName:
    type: string
    isRequired: true
    description: "Agent display name"

React PropTypes 비교​

React PropTypes를 알고 있다면 여기 매핑이 있습니다:

React PropTypesCrewX 스키마예제
PropTypes.stringtype: stringname: "value"
PropTypes.numbertype: numbercount: 42
PropTypes.booltype: boolenabled: true
PropTypes.arraytype: arrayitems: [1, 2, 3]
PropTypes.arrayOf(PropTypes.string)type: arrayOf, itemType: stringtags: ["a", "b"]
PropTypes.oneOf(["a", "b"])oneOf: ["a", "b"]mode: "a"
.isRequiredisRequired: true필수 필드

레이아웃 해석​

해석 순서​

CrewX는 두 단계로 레이아웃을 해석합니다:

  1. 내장 레이아웃 - CrewX 시스템에서 로드 (templates/agents/*.yaml)
  2. Props 재정의 - crewx.yaml에서 사용자 제공 props 적용 (props가 있는 사용자 정의 레이아웃)
┌─────────────────────────┐
│  Built-in Layout        │  단계 1: 기본 레이아웃 로드
│  (crewx/default or      │         (default/minimal)
│   crewx/minimal)        │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Custom Layout Props    │  단계 2: Props 적용
│  (if using custom       │         (사용자 정의 레이아웃만)
│   layout)               │
└─────────────────────────┘
            │
            ▼
┌─────────────────────────┐
│  Final Layout           │  결과: 에이전트 프롬프트와 함께
│                         │         렌더링된 레이아웃
└─────────────────────────┘

Props 재정의 예제 (사용자 정의 레이아웃)​

사용자 정의 레이아웃 정의:

# my-custom-layout.yaml (사용자 정의 레이아웃)
id: "my/custom-layout"
propsSchema:
  theme:
    type: string
    defaultValue: "auto"
  maxItems:
    type: number
    defaultValue: 10

crewx.yaml에서 재정의:

# crewx.yaml (프로젝트)
agents:
  - id: my_agent
    inline:
      layout:
        id: "my/custom-layout"
        props:
          theme: "dark"      # 재정의: "auto" → "dark"
          maxItems: 20       # 재정의: 10 → 20
      prompt: |
        Your instructions here.

최종 렌더링된 레이아웃:

  • theme = "dark" (재정의됨)
  • maxItems = 20 (재정의됨)

폴백 동작​

시나리오동작예제
레이아웃 존재지정된 레이아웃 사용layout: "crewx/minimal" → 최소 로드
레이아웃 찾을 수 없음crewx/default로 폴백layout: "unknown/layout" → 기본값 사용 + 경고
Props 유효하지 않음 (관대 모드)기본값 사용 + 경고유효하지 않은 prop → 기본값 사용
Props 유효하지 않음 (엄격 모드)오류, 실행 중지유효하지 않은 prop → 오류 발생

검증 모드​

관대 모드 (기본값):

  • 유효하지 않은 props → 기본값 사용
  • 알 수 없는 props → 경고와 함께 무시
  • 누락된 필수 props → 사용 가능한 경우 기본값 사용

엄격 모드:

  • 유효하지 않은 props → 검증 오류 발생
  • 알 수 없는 props → 검증 오류 발생
  • 누락된 필수 props → 검증 오류 발생

구성은 CrewX 시스템에서 설정되며 사용자 구성이 불가능합니다.

모범 사례​

1. 간단하게 시작​

사용자 정의 레이아웃을 만들기 전에 내장 레이아웃으로 시작하세요:

# ✅ 좋음: 내장 레이아웃으로 시작
agents:
  - id: my_agent
    inline:
      layout: "crewx/default"
      prompt: |
        Your instructions.

2. 의미 있는 Prop 이름 사용​

Props를 자체 문서화하도록 만드세요:

# ✅ 좋음: 명확한 prop 이름
props:
  maxContextDocuments: 20
  enableConversationHistory: true

# ❌ 나쁨: 암호화된 이름
props:
  max: 20
  en: true

3. 기본값 제공​

레이아웃 정의에서 항상 합리적인 기본값을 설정하세요:

propsSchema:
  theme:
    type: string
    defaultValue: "auto"  # ✅ 기본값 제공됨

  mode:
    type: string
    # ❌ 기본값 없음 - 사용자가 항상 지정해야 함

4. Props 문서화​

Props의 목적을 설명하려면 description을 사용하세요:

propsSchema:
  maxContextDocs:
    type: number
    min: 1
    max: 50
    defaultValue: 10
    description: "최대 로드할 컨텍스트 문서 수입니다. 값이 높을수록 컨텍스트는 개선되지만 토큰 사용이 증가합니다."  # ✅ 도움말

5. 유형 제약 사용​

oneOf, min, max를 사용하여 조기에 오류를 포착하세요:

propsSchema:
  theme:
    type: string
    oneOf: ["light", "dark", "auto"]  # ✅ 입력 검증
    defaultValue: "auto"

  # ❌ 제약 없음 - 모든 문자열 허용 (오타 가능)
  theme:
    type: string
    defaultValue: "auto"

6. 레이아웃을 집중력 있게 유지​

각 레이아웃은 특정 목적을 제공해야 합니다:

# ✅ 좋음: 집중된 레이아웃
- crewx/default   → 완벽한 컨텍스트가 있는 전체 에이전트 프로필
- crewx/minimal   → 간단한 에이전트를 위한 가벼운 래퍼

# ❌ 나쁨: 모든 것을 하려는 하나의 레이아웃
- crewx/mega-layout  → 20가지 다른 모드와 수많은 props 지원

7. 보안 고려사항​

절대 비밀을 하드코딩하지 마세요:

# ❌ 절대 이렇게 하지 마세요
props:
  apiKey: "sk-1234567890"  # 하드코딩된 비밀

대신 환경 변수를 사용하세요:

# ✅ 프롬프트에서 환경 변수 참조
prompt: |
  API Key: {{env.API_KEY}}  # 안전함: 환경에서

시스템 레이아웃만 신뢰하세요:

  • 내장 CrewX 레이아웃은 보안 검토됨
  • 사용자 정의 레이아웃은 보안 검토를 받아야 함
  • Props는 CrewX에서 삭제 및 이스케이프됨

예제​

예제 1: 기본 레이아웃이 있는 간단한 에이전트​

시나리오: 기본 코드 검토 에이전트를 만드세요.

agents:
  - id: code_reviewer
    name: "Code Review Assistant"
    inline:
      provider: "cli/claude"
      layout: "crewx/default"  # 간단한 기본값 사용
      prompt: |
        You are a code review assistant.

        Review code for:
        - Type safety
        - Error handling
        - Performance issues
        - Security vulnerabilities

        Provide constructive feedback with examples.

사용법:

crewx query "@code_reviewer review my authentication code"

예제 2: 간단한 작업을 위한 최소 에이전트​

시나리오: 간단하고 집중된 작업을 위한 경량 도우미를 만드세요.

agents:
  - id: quick_helper
    name: "Quick Helper"
    inline:
      provider: "cli/claude"
      layout: "crewx/minimal"  # 가벼운 래퍼
      prompt: |
        You are a quick helper for simple questions.

        Keep answers:
        - Concise and to the point
        - Clear and actionable
        - Under 3 sentences when possible

        Focus on efficiency and speed.

사용법:

crewx query "@quick_helper what is the syntax for array map in JavaScript?"
crewx query "@quick_helper explain git rebase in one sentence"

예제 3: 레이아웃 공유 여러 에이전트​

시나리오: 같은 레이아웃 구조를 공유하는 프론트엔드 및 백엔드 전문가를 만드세요.

agents:
  - id: frontend_specialist
    name: "Frontend Expert"
    inline:
      provider: "cli/claude"
      layout: "crewx/default"  # 공유 구조
      prompt: |
        You are a frontend development specialist.

        Expertise:
        - React, Vue, Angular
        - CSS, Tailwind, styled-components
        - Browser APIs and optimization

  - id: backend_specialist
    name: "Backend Expert"
    inline:
      provider: "cli/gemini"
      layout: "crewx/default"  # 같은 구조, 다른 콘텐츠
      prompt: |
        You are a backend development specialist.

        Expertise:
        - Node.js, Python, Go
        - Database design (SQL, NoSQL)
        - API design and security

이점:

  • 에이전트 간 일관된 프롬프트 구조
  • 유지 관리 용이 (레이아웃 한 번 업데이트)
  • 명확한 관심사 분리

예제 4: 사용 사례에 따라 레이아웃 선택​

시나리오: 다양한 복잡도 수준에 대해 다른 레이아웃을 사용하세요.

agents:
  - id: simple_qa
    name: "Simple Q&A Assistant"
    inline:
      layout: "crewx/minimal"  # 간단한 작업을 위한 가벼움
      prompt: |
        You are a Q&A assistant for quick questions.
        Provide brief, direct answers without extra context.

  - id: complex_analyst
    name: "Complex Analysis Assistant"
    inline:
      layout: "crewx/default"  # 복잡한 작업을 위한 전체 컨텍스트
      prompt: |
        You are an analysis assistant for complex technical questions.

        Provide comprehensive analysis including:
        - Root cause investigation
        - Multiple solution approaches
        - Trade-off analysis
        - Best practice recommendations

        Use full context and agent capabilities as needed.

예제 5: 점진적 개선​

시나리오: 간단하게 시작하여 필요에 따라 최적화하세요.

버전 1: 암시적 기본값으로 시작

agents:
  - id: assistant
    inline:
      # 암시적 crewx/default 레이아웃
      prompt: |
        You are a helpful assistant.

버전 2: 레이아웃 명시적으로 만들기

agents:
  - id: assistant
    inline:
      layout: "crewx/default"  # 명시적 선택
      prompt: |
        You are a helpful assistant.

버전 3: 성능 최적화

agents:
  - id: assistant
    inline:
      layout: "crewx/minimal"  # 효율성을 위해 최소값으로 전환
      prompt: |
        You are a helpful assistant focused on quick responses.

참고 자료​

관련 문서​

빠른 링크​

사용자의 경우:

개발자의 경우: