오늘의 오픈 소스 프로젝트 (#109): Trellis — 프로젝트 사양, 작업 및 메모리를 저장소에 영구 저장하기

서론

"AI 코딩은 10%의 코딩과 90%의 스택 재설명으로 이루어집니다. Trellis는 AI 에이전트의 가장 최악인 부분, 즉 건망증(amnesia)을 해결했습니다."

이 글은 Open Source Project of the Day 시리즈의 #109번째 기사입니다. 오늘의 프로젝트는 T trellis입니다. 이는 프로젝트 사양(specs), 작업 컨텍스트(task context), 그리고 세션 메모리(session memory)를 저장소(repository)에 영구적으로 저장하는 AI 코딩 에이전트 하네스(harness)입니다.

당신은 Claude Code와 함께 컨벤션(conventions)을 설명하고, 컨텍스트(context)를 설정하며, 좋은 결과물을 만들어내며 세션을 보냅니다. 그리고 터미널을 닫습니다. 다음 날, 다시 처음부터 시작해야 합니다. 기술 스택(tech stack) 선택을 다시 설명하고, 코드 스타일(code style)을 다시 묘사하며, 현재 작업의 배경을 다시 설정해야 합니다.

이 현상에는 이름이 있습니다: 바로 **에이전트 건망증 (agent amnesia)**입니다. 모든 세션이 새로 시작되며, 축적된 모든 컨텍스트가 사라집니다.

Trellis는 기억되어야 할 것들을 저장소 내부에 저장합니다: 컨벤션을 위한 .trellis/spec/, 작업 및 PRD(제품 요구 사항 문서)를 위한 .trellis/tasks/, 세션 저널(session journals)을 위한 .trellis/workspace/가 그것입니다. 에이전트는 시작 시 이 파일들을 읽으므로, 다시 설명할 필요가 없습니다.

학습 내용

• 3개 디렉토리 시스템: 왜 spec / tasks / workspace가 각각 고유한 역할을 갖는지
• 4단계 워크플로우: Plan(계획) → Implement(구현) → Verify(검증) → Finish(완료)로 이어지는 완전한 루프
• Trellis 기술(Skills): 내장된 4가지 워크플로우 모듈이 각각 수행하는 역할
• CLAUDE.md / AGENTS.md와의 비교: 왜 단일 파일 접근 방식이 모놀리스(monoliths)가 되는지
• 팀 시나리오: 사양(specs)을 Git에 커밋하는 것이 팀 전체에 어떤 이점을 주는지
• 지원 플랫폼 및 초기화

사전 요구 사항

• Claude Code, Cursor 또는 유사한 AI 코딩 도구 사용 경험
• 기본적인 Git 워크플로우에 대한 숙련도
• CLAUDE.md 또는 .cursorrules 개념에 대한 기본적인 이해

프로젝트 배경

Trellis란 무엇인가?

Trellis는 AI 코딩 에이전트 하네스(harness)입니다. "AI를 위한 스캐폴딩(scaffolding)으로서, 당신의 컨벤션 경로를 따라 AI를 안내합니다."

"Harness"라는 용어는 2026년 AI 코딩 논의에서 점점 더 많은 관심을 얻고 있습니다. 이는 에이전트 자체를 의미하는 것이 아니라, 에이전트 주변에 구축된 제약 조건(constraints), 메모리(memory), 그리고 워크플로 구조(workflow structure)를 의미합니다. Trellis는 이 분야에서 가장 체계적인 오픈 소스 구현체 중 하나로, 학술 연구(OpenReview의 "Agent Harness Engineering: A Survey" 논문)에서도 인용된 바 있습니다.

핵심 설계 결정: 모든 것을 Git 저장소 내부에 영구 저장(persist)하는 것입니다. 사양(Specs)은 코드 리뷰를 받을 수 있고, 세션 메모리(Session memory)는 팀 단위로 공유될 수 있습니다. 작업 컨텍스트(Task context)는 다양한 도구 간에 작동합니다. 이는 단순한 파일 경로의 선택이 아니라, AI 작업 패턴을 엔지니어링 관리 시스템(engineering management system)으로 가져오겠다는 결정입니다.

저자 / 팀

• 조직: Mindfold AI (mindfold-ai)
• 문서: docs.trytrellis.app
• 라이선스: AGPL-3.0
• 스택: TypeScript 67.9% / Python 25.8%

프로젝트 통계

• ⭐ GitHub Stars: 11,300+
• 🍴 Forks: 641+
• 💻 지원 플랫폼: 16개 AI 코딩 플랫폼
• 📄 라이선스: AGPL-3.0

핵심 기능

3단계 디렉토리 시스템

Trellis는 저장소 루트에 세 개의 하위 디렉토리를 가진 .trellis/ 디렉토리를 유지합니다.

.trellis/
├── spec/           ← 프로젝트 컨벤션 (Git에 커밋)
│   ├── coding-standards.md
...

spec/: 핵심 요소입니다. 매 세션마다 에이전트에게 다시 설명하고 싶지 않은 모든 것, 즉 기술 선택의 근거, 코드 스타일 규칙, 아키텍처 제약 조건, 명명 규칙(naming conventions), 알려진 함정(known pitfalls) 등이 포함됩니다. Git에 커밋되며, 세션 시작 시 에이전트의 컨텍스트(context)에 자동으로 주입됩니다.

tasks/: 작업(Tasks)은 단순한 한 줄 설명이 아닌 완전한 작업 단위입니다. 각 작업은 PRD(제품 요구 사항 문서, product requirements document), 구현 컨텍스트(implementation context, 코드를 작성하기 전 에이전트가 알아야 할 모든 것), 그리고 리뷰 컨텍스트(review context, diff를 무엇과 대조하여 확인할 것인지)를 가집니다.

workspace/: 개발자별 세션 저널 (session journals). 이번 세션에서 발생한 일, 직면한 문제, 그리고 다음 세션에서 작업을 이어가기 위해 알아야 할 사항들을 기록합니다. 에이전트는 새로운 세션이 시작될 때 이 파일을 읽습니다.

4단계 워크플로우 (4-Phase Workflow)

Trellis는 완전한 작업 루프를 정의합니다:

Plan → Implement → Verify → Finish
  ↑                                ↓
  └──────── spec updated ←─────────┘

1단계: 계획 (Phase 1: Plan (trellis-brainstorm))

코드를 작성하기 전에 요구사항을 명확히 합니다:

trellis-brainstorm 호출
    ↓
에이전트가 요구사항 명확화 과정을 안내합니다:
...

2단계: 구현 (Phase 2: Implement (trellis-implement))

실행 시점에 컨텍스트가 자동으로 주입됩니다:

trellis-implement 호출
    ↓
자동으로 읽어들임:
...

3단계: 검증 (Phase 3: Verify (trellis-check))

코드 작성 후 자동화된 리뷰를 수행합니다:

trellis-check 호출
    ↓
사양(spec)과 비교: diff가 표준을 준수하는가?
...

4단계: 완료 (Phase 4: Finish (trellis-update-spec))

루프에서 가장 가치 있는 부분입니다:

trellis-update-spec 호출
    ↓
이번 작업에서 발견된 새로운 패턴, 컨벤션(conventions), 규칙을 분석
...

CLAUDE.md / AGENTS.md와의 비교

CLAUDE.md / .cursorrules의 문제점:
  단일 파일 → 시간이 지남에 따라 모든 것을 때려 넣는 쓰레기통으로 변함
  일괄 주입 (Bulk injection) → 작업 관련성과 상관없이 모든 것이 컨텍스트에 포함됨
...

Trellis는 CLAUDE.md를 대체하는 것이 아니라, 그 주변에 구조를 구축합니다. 여전히 CLAUDE.md를 사용할 수 있으며, Trellis 사양(spec) 파일들이 이를 보완합니다.

심층 분석 (Deep Dive)

설치 및 초기화 (Installation and Initialization)

# Trellis CLI 설치
npm install -g @mindfoldhq/trellis@latest

...

trellis init은 다음을 수행합니다:

1. .trellis/ 디렉토리 구조 생성
2. 감지된 도구들을 위한 플랫폼별 설정 파일 생성
3. 초기 사양(spec) 템플릿 생성 (기존 코드를 바탕으로 AI가 생성 가능)
4. 선호도에 따라 워크스페이스 디렉토리의 .gitignore 처리

기존 프로젝트를 위한 초기 사양(specs) 생성:

Claude Code에서:
"이 코드베이스를 분석하여 기술 스택(tech stack), 코드 스타일(code style), 아키텍처 제약 사항(architectural constraints)을 포함하는 초기 .trellis/spec/ 콘텐츠를 생성해줘"
...

플랫폼 지원 (Platform Support)

Trellis는 16개의 AI 코딩 플랫폼을 지원하며, 플랫폼별 맞춤형 설정을 생성합니다:

확인된 지원 플랫폼: Claude Code, Cursor, OpenCode, Codex, GitHub Copilot, Devin 등.

특히 Claude Code의 경우, Trellis는 구조화된 CLAUDE.md와 그에 상응하는 Skill 파일들을 생성하여, Claude Code가 언제 trellis-brainstorm, trellis-implement 및 기타 워크플로우 모듈을 호출해야 하는지 알 수 있게 합니다.

Trellis Skill 시스템 (Trellis Skill System)

네 가지 내장된 Skill이 워크플로우 진입점(entry points)을 정의합니다:

Skill	사용 시점	핵심 동작
trellis-brainstorm	새로운 작업 시작 시	요구사항 명확화 가이드, PRD 출력
...

이 Skill들은 android/skills 및 생태계 내의 다른 프로젝트들이 사용하는 것과 동일한 형식인 agentskills.io 오픈 표준을 따릅니다.

팀 워크플로우 (Team Workflow)

사양(spec) 파일이 Git에 커밋되면, 팀 전체가 동일한 표준의 혜택을 누리게 됩니다:

시나리오: 새로운 팀원이 합류할 때
기존 방식: Confluence에 있는 문서(오래되었을 가능성 있음); 시니어 개발자에게 질문; 시행착오를 거치며 적응
Trellis:
...

시나리오: 팀이 새로운 베스트 프랙티스(best practice)를 발견했을 때
기존 방식: 구두 지식 전달, 또는 아무도 읽지 않는 문서 업데이트
Trellis:
...

워크스페이스 저널 형식 (Workspace Journal Format)

세션 저널(Session journals)은 에이전트에게 세션 간의 연속성을 제공합니다:

# Journal - 사용자이름

## 2026-06-28
...

다음 세션이 시작될 때, 에이전트는 이 저널을 읽고 컨텍스트(context)를 이해하므로 다시 브리핑할 필요가 없습니다.

빠른 시작 (Quick Start)

# 설치
npm install -g @mindfoldhq/trellis@latest

...

링크 및 리소스 (Links and Resources)

• 🌟 GitHub: mindfold-ai/Trellis
• 📖 Docs: docs.trytrellis.app
• 🏢 Mindfold AI: github.com/mindfold-ai

결론 (Conclusion)

Trellis는 AI 코딩 툴체인(toolchain)의 체계적인 문제를 해결합니다. 즉, 모든 세션이 프로젝트의 컨텍스트(context), 팀의 컨벤션(conventions), 또는 이전 세션의 진행 상황에 대한 인지 없이 제로 상태에서 시작된다는 점입니다.

사양(specs), 작업 컨텍스트(task context), 그리고 세션 메모리(session memory)를 Git 저장소 내부에 저장하는 것은 단순한 구현 세부 사항이 아닌 설계 결정(design decision)입니다. 이는 AI 작업 패턴이 엔지니어링 관리 시스템(engineering management system)에 편입됨을 의미합니다. 즉, 사양을 검토할 수 있고, 메모리를 공유할 수 있으며, 변경 사항을 추적할 수 있습니다.

폐쇄 루프 워크플로(closed-loop workflow) 설계 — 특히 학습된 내용을 다시 사양으로 반영하는 종료(Finish) 단계 — 는 시스템이 매번 동일한 기준점에서 시작하는 대신, 사용함에 따라 개선됨을 의미합니다.

11.3k개의 스타(Stars)는 실제 수요를 나타냅니다. 여러 프로젝트나 도구를 전환하며 작업하는 개발자, 또는 팀 전체에 AI 지원 개발 관행을 표준화하려는 기술 리드(tech leads)에게 Trellis는 진지하게 검토할 가치가 있습니다.

엄선된 AI 에이전트(Agents)와 기술을 위한 마켓플레이스인 PrimeSkills를 탐색해 보세요. 각 기술은 실제 기업 워크플로(workflows)에서 검증되었으며, 과장된 광고를 걷어내고 실제로 작동하는 것만을 유지합니다.

더 유용한 통찰력과 흥미로운 제품을 보시려면 저의 홈페이지를 방문해 주세요.