Molayo

© 2026 Molayo

GitHub요약2026. 05. 20. 16:26

coleam00/Linear-Coding-Agent-Harness

요약

Claude Agent SDK를 활용하여 Linear 프로젝트 관리 시스템과 연동된 자율 코딩 에이전트 데모를 구현한 프로젝트입니다. Initializer 에이전트가 이슈를 생성하면 Coding 에이전트가 이를 구현하는 2-에이전트 패턴을 통해, 모든 작업 과정과 세션 핸드오프가 Linear 이슈와 댓글을 통해 실시간으로 추적됩니다.

핵심 포인트

  • Linear를 프로젝트 관리 및 에이전트 간 통신 채널로 활용하여 작업 가시성 확보
  • Initializer와 Coding 에이전트가 협업하는 2-에이전트 패턴 구현
  • Puppeteer MCP를 통한 브라우저 기반 UI 검증 및 테스트 자동화
  • Claude Opus 4.5 모델을 기반으로 한 고성능 자율 코딩 워크플로우 제공

Claude Agent SDK를 사용하여 장기 실행되는 자율 코딩 (autonomous coding)을 시연하는 최소한의 하네스 (harness)입니다. 이 데모는 모든 작업을 추적하기 위해 Linear를 핵심 프로젝트 관리 시스템으로 사용하는 2-에이전트 패턴 (initializer + coding agent)을 구현합니다.

Linear 통합: 모든 작업은 로컬 파일이 아닌 Linear 이슈 (issues)로 추적됩니다
실시간 가시성: Linear 워크스페이스에서 에이전트의 진행 상황을 직접 확인하세요
세션 핸드오프 (Session Handoff): 에이전트는 텍스트 파일이 아닌 Linear 댓글을 통해 통신합니다
2-에이전트 패턴: Initializer가 Linear 프로젝트 및 이슈를 생성하면, 코딩 에이전트가 이를 구현합니다
브라우저 테스트: UI 검증을 위한 Puppeteer MCP 사용
Claude Opus 4.5: 기본적으로 Claude의 가장 강력한 모델을 사용합니다

# Claude Code CLI 설치 (최신 버전 필요)
npm install -g @anthropic-ai/claude-code
# Python 의존성 설치
...

두 개의 인증 토큰이 필요합니다:

Claude Code OAuth 토큰:

# Claude Code CLI를 사용하여 토큰 생성
claude setup-token
# 환경 변수 설정
...

Linear API 키:

# 다음에서 API 키를 가져오세요: https://linear.app/YOUR-TEAM/settings/api
export LINEAR_API_KEY='lin_api_xxxxxxxxxxxxx'

claude --version # 최신 버전이어야 함
pip show claude-code-sdk # SDK가 설치되었는지 확인

python autonomous_agent_demo.py --project-dir ./my_project

반복 횟수를 제한하여 테스트하려면:

python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3

┌─────────────────────────────────────────────────────────────┐
│ LINEAR-INTEGRATED WORKFLOW │
├─────────────────────────────────────────────────────────────┤
...

Initializer Agent (세션 1):

  • app_spec.txt를 읽습니다.

  • 팀 목록을 나열하고 새로운 Linear 프로젝트를 생성합니다.

  • 상세한 테스트 단계가 포함된 50개의 Linear 이슈를 생성합니다.

  • 세션 추적을 위한 META 이슈를 생성합니다.

  • 프로젝트 구조, init.sh, 그리고 git을 설정합니다.

  • 읽기 (Reads)

코딩 에이전트 (Coding Agent) (세션 2+):

  • Linear에서 우선순위가 가장 높은 Todo 이슈를 조회합니다.
  • 이전에 완료된 기능에 대해 검증 테스트 (verification tests)를 실행합니다.
  • 이슈를 점유합니다 (상태 → In Progress)
  • 기능을 구현합니다.
  • Puppeteer 브라우저 자동화 (browser automation)를 통해 테스트합니다.
  • 이슈에 구현 관련 코멘트를 추가합니다.
  • 완료로 표시합니다 (상태 → Done)
  • 세션 요약 내용을 포함하여 META 이슈를 업데이트합니다.

로컬 텍스트 파일 대신, 에이전트는 다음을 통해 통신합니다:

이슈 코멘트 (Issue Comments): 구현 세부 사항, 차단 요소 (blockers), 컨텍스트
META 이슈 (META Issue): 세션 요약 및 핸드오프 (handoff) 노트
이슈 상태 (Issue Status): Todo / In Progress / Done 워크플로우

변수 (Variable)설명 (Description)필수 여부 (Required)
CLAUDE_CODE_OAUTH_TOKENClaude Code OAuth 토큰 (claude setup-token에서 생성)예
LINEAR_API_KEYMCP 액세스를 위한 Linear API 키예
옵션 (Option)설명 (Description)기본값 (Default)
--project-dir프로젝트 디렉토리./autonomous_demo_project
--max-iterations에이전트 최대 반복 횟수제한 없음
--model사용할 Claude 모델claude-opus-4-5-20251101
linear-agent-harness/
├── autonomous_agent_demo.py # 메인 엔트리 포인트 (Main entry point)
├── agent.py # 에이전트 세션 로직 (Agent session logic)
...

실행 후, 프로젝트 디렉토리에는 다음이 포함됩니다:

my_project/
├── .linear_project.json # Linear 프로젝트 상태 (마커 파일)
├── app_spec.txt # 복사된 명세서 (specification)
...
서버 (Server)전송 방식 (Transport)목적 (Purpose)
LinearHTTP (Streamable HTTP)프로젝트 관리 - 이슈, 상태, 코멘트
PuppeteerstdioUI 테스트를 위한 브라우저 자동화

이 데모는 심층 방어 (defense-in-depth) 보안을 사용합니다 (security.py 및 client.py 참조):

OS 레벨 샌드박스 (OS-level Sandbox): Bash 명령어가 격리된 환경에서 실행됩니다.
파일 시스템 제한 (Filesystem Restrictions): 파일 작업이 프로젝트 디렉토리로 제한됩니다.
Bash 허용 목록 (Bash Allowlist): 특정 명령만 허용됩니다 (npm, node, git 등).
MCP 권한 (MCP Permissions): 보안 설정에서 명시적으로 허용된 도구만 사용 가능합니다.

실행하기 전에 다음 사항을 확인하십시오:

  • 최소 하나 이상의 팀이 포함된 Linear 워크스페이스 (Linear workspace)
  • 읽기/쓰기 권한이 있는 API 키 (Settings > API에서 발급)
  • 에이전트가 팀을 자동으로 감지하고 프로젝트를 생성합니다.

초기화 에이전트 (initializer agent)는 다음을 생성합니다:

  • 귀하의 앱 이름을 딴 새로운 Linear 프로젝트
  • app_spec.txt를 기반으로 한 50개의 기능 이슈 (feature issues)
  • 세션 추적 및 핸드오프 (handoff)를 위한 1개의 META 이슈

이후의 모든 코딩 에이전트 (coding agents)는 이 Linear 프로젝트를 기반으로 작동합니다.

빌드할 다른 애플리케이션을 지정하려면 prompts/app_spec.txt를 편집하십시오.

원하는 이슈 개수로 변경하려면 prompts/initializer_prompt.md를 편집하고 "50 issues"를 수정하십시오.

ALLOWED_COMMANDS에서 명령어를 추가하거나 제거하려면 security.py를 편집하십시오.

"CLAUDE_CODE_OAUTH_TOKEN not set"
claude setup-token을 실행하여 토큰을 생성한 다음, 이를 export 하십시오.

"LINEAR_API_KEY not set"
https://linear.app/YOUR-TEAM/settings/api에서 API 키를 가져오십시오.

"Appears to hang on first run"
정상적인 동작입니다. 초기화 에이전트가 상세한 설명이 포함된 Linear 프로젝트와 50개의 이슈를 생성하고 있습니다. [Tool: mcp__linear__create_issue] 출력을 확인하십시오.

"Command blocked by security hook"
에이전트가 허용되지 않은 명령어를 실행하려고 시도했습니다. 필요한 경우 security.py의 ALLOWED_COMMANDS에 해당 명령어를 추가하십시오.

"MCP server connection failed"
LINEAR_API_KEY가 유효하며 적절한 권한을 가지고 있는지 확인하십시오. Linear MCP 서버는 https://mcp.linear.app/mcp에서 HTTP 전송 (HTTP transport)을 사용합니다.

Linear 워크스페이스를 열면 다음을 확인할 수 있습니다:

  • 초기화 에이전트가 생성한 프로젝트
  • 프로젝트 아래에 정리된 50개의 모든 이슈
  • 실시간 상태 변경 (Todo → In Progress → Done)
  • 각 이슈에 대한 구현 코멘트 (implementation comments)
  • META 이슈의 세션 요약 (session summaries)

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0