Grok Build Source Course · 12 / 24

Coding Agent 설계 워크벤치

최종 과제는 기능 목록에서 실행 가능한 시스템 설계로 격상됩니다. 9개 차원에 걸쳐 명확한 결정을 내려야 하며, 각 결정에는 계약, 장애 경로, 검증 방법, 제출 가능한 성과물이 포함되어야 합니다.

9 Decisions9 DeliverablesArchitecture + PoCEvidence Review
01 / OBJECTIVES

강의 목표

시스템 경계 완성

진입점, 상태 소유권, 모델 루프, 외부 확장의 책임 경계를 정의합니다.

장애 설계 보완

도구, 보안, 영속성, 복구, 상태 알림에 대한 장애 경로를 그립니다.

검토 가능한 성과물 산출

ADR, 계약, 위협 모델, 테스트, 최소 데모를 제출합니다 — 개념도에 머물지 않습니다.

02 / CORE VISUAL

한 눈에 보는 완전한 Agent 시스템

03 / BRIEF

최종 프로젝트 브리핑

과제

실제 팀을 위한 "저장소 수준 Coding Agent"를 설계하세요. 최소한 코드 읽기, 계획 제안, 파일 수정, 검증 실행, 중단된 세션 복구가 가능해야 합니다. 최소 PoC 구현은 허용되지만, 아키텍처 문서는 반드시 9개 차원 전체를 포함해야 합니다.

하드 제약
  • 기본 최소 권한 원칙
  • 모든 외부 동작 추적 가능
  • 충돌 후 복구 설명 가능
  • 민감 데이터의 명확한 저장 위치
  • 확장 코드의 신뢰 경계
04 / WORKBENCH

9차원 결정 카드

ENTRY

진입점

누가 Agent를 시작하며, 대화형·CI·IDE 모드는 같은 코어를 공유하나요?

소스 앵커: pager-bin composition root, shell headless/stdio, ACP gateway.

제출 성과물진입점 매트릭스 + CLI 인수 초안 + 엔드투엔드 시작 시퀀스 다이어그램 1개.
STATE

상태 / 동시성

누가 세션 상태를 소유하며, 모델 스트림과 도구 작업은 어떻게 취소·큐잉·반환되나요?

소스 앵커: SessionActor, LocalSet, 백그라운드 summary/persistence actor.

제출 성과물상태 소유권 다이어그램 + 동시성 시퀀스 + 레이스 컨디션 테스트 체크리스트.
MODEL LOOP

모델 루프

Prompt, 스트리밍 출력, 도구 호출, 재시도, 중단, 모델 전환은 어떻게 폐루프를 형성하나요?

소스 앵커: run_loop, turn, tool_dispatch, model_switch, two_pass.

제출 성과물모델 루프 상태 머신 + 중단 조건 + 3가지 API 오류 전략.
TOOLS

도구 계약

입력 Schema, 반환값, 오류, 타임아웃, 멱등성, 권한 등급은 어떻게 표준화되나요?

소스 앵커: ToolKind, Tool Bridge, server__tool, capability filter.

제출 성과물JSON Schema 2개 + 오류 분류표 + 계약 테스트.
CONTEXT

컨텍스트 / 메모리

단기 Context는 언제 압축하며, 장기 메모리는 무엇을 쓰고·언제 검색하고·어떻게 삭제하나요?

소스 앵커: compaction segments, two-pass, memory FTS/embedding/MMR/Dream.

제출 성과물Token 예산표 + 압축 알고리즘 + 메모리 리콜 및 망각 테스트.
SECURITY

보안

권한, 샌드박스, Hook, 네트워크, 플러그인 신뢰는 각각 어느 레이어의 보증을 담당하나요?

소스 앵커: capability, sandbox, Hooks fail-open, plugin-root trust.

제출 성과물위협 모델 + 권한 매트릭스 + 공격 시나리오 5개.
RECOVERY

영속성 / 복구

메시지, 도구 결과, 파일 checkpoint, 외부 연결 상태는 어떻게 영속화하고 재생하나요?

소스 앵커: session persistence, chat persistence, rewind, MCP restart.

제출 성과물스토리지 Schema + 충돌 주입 스크립트 + RPO/RTO 선언.
OBSERVABILITY

관측가능성 / 프라이버시

어떤 이벤트가 로그와 지표에 들어가며, 어떤 내용은 익명화·샘플링·로컬 외부 전송 금지가 필요한가요?

소스 앵커: file-utils events, telemetry enums, MCP status payload.

제출 성과물이벤트 사전 + 익명화표 + SLO 3개와 진단 쿼리.
EXTENSIONS

확장 생태계

MCP, Plugin, Hook의 발견·버전·활성화·신뢰·제거는 어떻게 관리하나요?

소스 앵커: marketplace index, manifest, install registry, trust store.

제출 성과물플러그인 manifest + 신뢰 라이프사이클 + 호환성 정책.
05 / SOURCE MAP

실제 소스코드 증거 내비게이션

진입점 & 세션xai-grok-pager-bin/src/main.rs
xai-grok-shell/src/session/acp_session.rs
모델 & 도구session/acp_session_impl/run_loop.rs
xai-grok-workspace/src/capability.rs
컨텍스트 & 메모리session/compaction.rs · two_pass.rs
xai-grok-memory/src/
보안 & Hooksxai-grok-sandbox
xai-grok-hooks/src/dispatcher.rs
복구 & 상태session/persistence.rs
mcp_dispatcher.rs · mcp_restart.rs
확장xai-grok-plugin-marketplace/src/
xai-grok-agent/src/plugins/
EVIDENCE EXAMPLE

모든 설계 결정은 실제 소스 브랜치로 추적될 수 있어야 합니다

// 플러그인 루트를 canonicalize할 수 없을 때 신뢰 부여하지 않음
match dunce::canonicalize(plugin_root) {
    Ok(canonical) => self.trusted.contains(&canonical),
    Err(_) => false,
}

여러분의 설계도 마찬가지로 장애 기본값을 명시해야 합니다. 정책을 읽을 수 없거나, 도구 결과를 파싱할 수 없거나, checkpoint를 복구할 수 없을 때 시스템은 각각 중단·다운그레이드·사용자 요청 중 어떤 동작을 해야 합니까?

crates/codegen/xai-grok-agent/src/plugins/trust.rs
06 / RUBRIC

100점 평가 루브릭

20경계 & ADR
20계약 & 상태 머신
25보안 & 복구
20테스트 & 관측가능성
15데모 & 증거

자동 탈락 항목: 민감 데이터 저장 위치 미명시; 고위험 도구에 권한 경로 없음; 충돌 후 복구 가능하다고 주장하나 테스트 없음; 소스코드 인용 시 파일 경로 제공 불가.

07 / FINAL LAB

실습: 90분 설계 스프린트

90 MIN

최종 제출 패키지
검토 가능한 설계 아카이브

  1. 15분: 사용자, 저장소, 실행 권한, 성공 기준을 정의합니다.
  2. 20분: 핵심 비주얼과 9차원 결정 카드를 작성하고 모든 상태 소유자를 표시합니다.
  3. 20분: 도구 계약 하나와 모델-도구 최소 호출 체인을 구현합니다.
  4. 15분: 타임아웃, 권한 거부, 프로세스 충돌을 주입하고 복구 결과를 기록합니다.
  5. 10분: 데이터 흐름, 익명화, 플러그인 신뢰 검사를 완료합니다.
  6. 10분: 루브릭으로 자가 평가 후 ADR 3개, 테스트 기록, 5분 데모 스크립트를 제출합니다.
핵심 정리

Coding Agent의 완성도는 경계와 장애 경로에 드러납니다. 9차원 워크벤치는 모델 능력을 실행 가능하고, 복구 가능하며, 감사 가능하고, 확장 가능한 엔지니어링 시스템으로 전환하도록 도와줍니다.

소스코드 스냅샷 주의사항: 이 페이지는 로컬 grok-build-main을 설계 사례 라이브러리로 사용하며, 경로 앵커는 실제 소스코드에서 가져왔습니다. 워크벤치의 납품 형식은 강의 설계 결과물이며 Grok Build의 공식 아키텍처 템플릿을 주장하지 않습니다. 수강생은 다른 기술 스택을 사용할 수 있지만, 각 결정에는 동등한 수준의 증거가 필요합니다.