Trellis: 여러 AI 코딩 도구를 하나의 개발 워크플로로 묶는 오픈소스 프레임워크

AI 코딩 도구가 좋아질수록 역설적으로 팀의 개발 방식은 더 산만해진다.

누군가는 Claude Code를 쓰고, 누군가는 Cursor를 쓰고, 또 누군가는 Codex나 OpenCode를 쓴다. 문제는 모델 성능이 아니라 프로젝트 맥락이 계속 흩어진다는 것이다. 규칙은 CLAUDE.md에 있고, 작업 문맥은 이슈에 있고, 지난 세션의 결정은 채팅창에 남아 있고, 다음 날 다시 열면 AI는 또 처음부터 설명을 요구한다.

Trellis는 바로 이 문제를 겨냥한다. 새로운 에이전트 모델이 아니다. 더 똑똑한 IDE도 아니다. 대신 AI가 프로젝트를 이해하는 방식 자체를 파일과 워크플로로 구조화한다. 한마디로 말하면, “프롬프트를 잘 쓰는 법”이 아니라 “AI가 팀의 개발 프로세스를 따라오게 만드는 법”에 가깝다. (GitHub)

https://github.com/mindfold-ai/Trellis

GitHub - mindfold-ai/Trellis: The best agent harness.

 

프로젝트 소개

Trellis는 mindfold-ai가 공개한 멀티플랫폼 AI 코딩 프레임워크다. 저장소 소개 문구 그대로 보면 Claude Code, Cursor, Codex, OpenCode, Kilo, Kiro, Gemini CLI, Windsurf, GitHub Copilot 등 여러 AI 코딩 환경을 지원한다. 핵심 아이디어는 각 도구마다 따로 룰 파일을 관리하는 대신, 프로젝트 중심의 공통 구조를 .trellis/ 아래에 두고 각 플랫폼용 진입점과 설정 파일을 생성하는 것이다. (GitHub)

프로젝트의 중심 구조는 꽤 명확하다.

.trellis/
├── spec/         # 프로젝트 규칙, 코딩 컨벤션, 가이드
├── tasks/        # PRD, 구현 문맥, 상태 관리
├── workspace/    # 개발자별 저널과 세션 연속성
├── workflow.md   # 공통 워크플로 규칙
└── scripts/      # 자동화 스크립트

그리고 이 공통 구조를 바탕으로 .claude/, .cursor/, AGENTS.md, .agents/skills/, .github/copilot/ 같은 플랫폼별 파일을 만들어 준다. 즉 Trellis의 본질은 “AI 툴을 하나 더 추가하는 것”이 아니라, 도구 위에 공통 운영체제를 얹는 것이다. (GitHub)

기술 스택도 흥미롭다. CLI 패키지는 Node.js 기반이며 TypeScript로 작성되어 있고, 공식 기여 문서에는 Node.js 18+, pnpm, Python 3, Bash가 개발 전제 조건으로 제시된다. 실제로 패키지 스크립트에는 tsc, vitest, eslint, basedpyright가 보이고, 문서와 아키텍처 설명에서는 Python 훅 스크립트와 Bash 기반 워크플로가 함께 등장한다. 즉 Trellis는 TypeScript CLI + Python hooks + Git worktree + Markdown/JSONL 문맥 파일의 조합으로 이해하면 된다. (GitHub)

왜 이 프로젝트가 등장했을까

Trellis가 등장한 배경은 꽤 현실적이다.

기존 AI 코딩 도구들은 대체로 다음 세 가지 문제를 남긴다.

첫째, 규칙 파일이 비대해진다. CLAUDE.md, AGENTS.md, .cursorrules 같은 파일은 처음엔 편하지만, 시간이 지나면 모든 규칙이 한 파일에 몰리면서 검색도 어렵고 재사용도 힘들어진다. Trellis 문서도 이 점을 직접 언급하며, 기존 방식이 monolithic해지기 쉽다고 설명한다. (GitHub)

둘째, 작업 단위의 문맥이 유지되지 않는다. 지금 하고 있는 기능의 요구사항, 참고 파일, 검증 절차, 남은 체크리스트가 채팅창에만 있으면 세션이 바뀌는 순간 맥락이 날아간다. Trellis는 이를 tasks/와 workspace/로 파일화한다. 작업은 task 디렉터리로 남고, 개발자별 세션 저널도 별도로 축적된다. (GitHub)

셋째, 여러 AI 에이전트를 병렬로 돌리기 어렵다. 한 브랜치에서 여러 작업을 동시에 진행하면 충돌이 나기 쉽다. Trellis는 Git worktree 기반 병렬 작업을 공식적인 패턴으로 끌어와, AI 작업을 서로 다른 작업 공간으로 분리하려고 한다. README에서도 “one branch into a traffic jam”을 피한다고 설명한다. (GitHub)

결국 Trellis는 “AI가 코드를 잘 쓰게 하자”보다 한 단계 위에 있다.
AI가 팀의 개발 프로세스를 어지럽히지 않게 하자.
이게 이 프로젝트의 출발점이다. (GitHub)

핵심 기능

1. Spec 기반 프로젝트 규칙 관리

Trellis의 가장 중요한 개념은 spec/이다. 여기에 프론트엔드 규칙, 백엔드 규칙, 디렉터리 구조, 품질 기준, 사고 가이드 같은 문서를 계층적으로 넣는다. 중요한 점은 이 문서가 단순 참고 문서가 아니라 AI가 읽어야 하는 공식 프로젝트 지식이라는 것이다. (docs.trytrellis.app)

예를 들어 이런 식으로 구성할 수 있다.

.trellis/spec/
├── frontend/
│   ├── index.md
│   ├── component-guidelines.md
│   ├── hook-guidelines.md
│   └── type-safety.md
├── backend/
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   └── quality-guidelines.md
└── guides/
    ├── index.md
    └── cross-layer-thinking-guide.md

이 구조가 좋은 이유는 규칙이 “한 덩어리 문서”가 아니라 영역별로 분리된 작은 문서 집합이 되기 때문이다. 팀원이 늘어도 관리가 쉽고, AI도 필요한 부분만 읽게 만들 수 있다. (docs.trytrellis.app)

2. Task 중심 개발 흐름

Trellis는 작업을 그냥 “대화 주제”로 두지 않는다. 하나의 task 디렉터리로 만든다. 문서에 따르면 작업 수명주기는 create → init-context → add-context → start → implement/check → finish → archive 흐름을 따른다. (docs.trytrellis.app)

즉, 기능 개발이 이렇게 바뀐다.

# 예시: 새 작업 생성
TASK_DIR=$(./.trellis/scripts/task.py create "Add user login" \
  --slug user-login \
  --assignee alice \
  --priority P1)

이 방식의 장점은 명확하다.

• 요구사항은 prd.md
• 구현 맥락은 JSONL 설정
• 현재 작업 포인터는 .current-task
• 완료 후에는 archive

이렇게 남는다.
채팅이 끝나도 작업은 사라지지 않는다.
AI가 바뀌어도 작업 자산은 남는다. (docs.trytrellis.app)

3. 세션 연속성과 프로젝트 메모리

보통 AI 코딩 도구의 가장 큰 낭비는 “어제 설명했던 걸 오늘 또 설명하는 것”이다.

Trellis는 workspace/{developer-name}/journal-N.md 같은 구조로 개발자별 세션 저널을 축적한다. Quick Start 문서에서도 -u your-name 옵션이 개인 워크스페이스를 만들고 세션 연속성을 제공한다고 설명한다. (GitHub)

예시 초기화는 이런 식이다.

npm install -g @mindfoldhq/trellis@latest

trellis init -u your-name

혹은 사용하는 도구만 골라서 시작할 수도 있다.

trellis init --cursor --opencode --codex -u your-name

즉 Trellis는 세션을 대화 로그가 아니라 프로젝트 메모리의 일부로 다룬다. 이건 실제 협업에서 꽤 큰 차이를 만든다. (GitHub)

4. 멀티플랫폼 지원

이 프로젝트가 특히 눈에 띄는 이유는 특정 벤더 종속성을 줄이려는 방향 때문이다.

문서에 따르면 Claude Code, Cursor, Codex, OpenCode, Kilo, Kiro 등은 각기 다른 설정 디렉터리와 명령 형식을 갖는다. 그런데 Trellis는 공통 .trellis/ 구조를 유지한 채, 각 플랫폼에 맞는 명령과 설정 파일을 생성한다. 예를 들어 Claude Code는 .claude/commands/, Cursor는 .cursor/commands/, Codex는 AGENTS.md와 .agents/skills/ 구조를 사용한다. (docs.trytrellis.app)

이건 팀 관점에서 매우 중요하다.
AI 도구를 갈아타도 프로젝트 규칙을 처음부터 다시 설계할 필요가 없다.
도구는 바뀌어도 작업 구조는 유지된다. (docs.trytrellis.app)

5. 병렬 에이전트 실행과 worktree 기반 격리

Trellis는 멀티에이전트 작업을 단순 “동시에 여러 에이전트 실행” 수준으로 보지 않는다. Git worktree를 사용해 각 작업을 분리된 작업 공간에서 다루게 한다. README와 Quick Start 모두 이 방향을 강조한다. (GitHub)

이 방식이 실무에서 좋은 이유는 간단하다.

• 브랜치 충돌 감소
• 기능별 실험 격리
• 병렬 작업의 책임 구분
• 검증 루프 독립 실행

즉, AI를 많이 붙일수록 더 혼란스러워지는 게 아니라, 오히려 더 기계적으로 관리할 수 있다.

6. 품질 검증 루프

문서에서 가장 흥미로운 부분 중 하나가 Ralph Loop다. 이것은 Claude Code 전용 품질 제어 메커니즘으로, Check Agent가 “끝났다”고 말했을 때 바로 끝내지 않고 ralph-loop.py 훅이 개입해 검증 명령을 실행한다. 예를 들어 worktree.yaml에 pnpm lint, pnpm typecheck, pnpm test를 넣어두면 모두 통과해야 작업이 진짜 끝난 것으로 본다. 최대 5회 반복 제한도 있다. (docs.trytrellis.app)

예시 설정은 이런 느낌이다.

verify:
  - pnpm lint
  - pnpm typecheck
  - pnpm test

이건 단순 자동화처럼 보이지만, 실제로는 매우 중요하다.
AI가 “완료”를 선언하는 순간을 신뢰하지 않고, 프로젝트가 정의한 검증 명령을 통과했는지로 완료를 판정하기 때문이다. 이 철학은 AI 도구를 실전 개발에 붙일 때 꼭 필요하다. (docs.trytrellis.app)

프로젝트 아키텍처 분석

Trellis를 한 문장으로 요약하면 이렇다.

공통 프로젝트 문맥을 .trellis/에 저장하고, 플랫폼별 훅/명령/에이전트 시스템을 통해 적절한 순간에 주입하는 구조다. (docs.trytrellis.app)

이를 블로그식으로 재구성하면 다음 그림이 가장 이해하기 쉽다.

이 구조에서 핵심은 세 가지다.

1. 세션 시작 시점에 문맥을 자동 수집한다

아키텍처 문서에 따르면 session-start.py는 세션 시작 시 자동으로 실행되어 개발자 identity, workflow, workspace 히스토리, Git 로그, task 상태를 읽어 문맥을 주입한다. /start 명령은 그 위에서 workflow.md를 읽고, get-context.py를 실행하고, spec index를 읽은 뒤 사용자에게 현재 작업을 묻는 흐름으로 동작한다. (docs.trytrellis.app)

즉 사용자는 매번 이렇게 설명할 필요가 없다.

우리 프로젝트는 Next.js고, 백엔드는 NestJS고, 에러 핸들링은 이렇게 하고, 지금 로그인 기능 작업 중이고, 어제 여기까지 했고…

이걸 Trellis는 파일 시스템에서 회수한다.

2. 작업별로 필요한 문맥만 JSONL로 주입한다

inject-subagent-context.py는 Trellis의 실질적인 엔진에 가깝다. 문서 설명에 따르면 메인 에이전트가 implement나 check 같은 서브 에이전트를 호출하면, 현재 task와 해당 JSONL 파일을 읽고 필요한 spec/파일/디렉터리만 주입한다. (docs.trytrellis.app)

예를 들어 implement.jsonl은 이런 식으로 생각할 수 있다.

{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": "src/services/", "type": "directory", "reason": "Existing service patterns"}

이 설계가 좋은 이유는 AI에게 모든 걸 읽히는 대신,
지금 작업에 필요한 문맥만 선택적으로 공급하기 때문이다.
토큰 낭비도 줄고, 규칙 충돌도 줄어든다. (docs.trytrellis.app)

3. 에이전트 역할을 명확히 분리한다

문서에는 dispatch, plan, implement, check, debug, research의 6개 빌트인 에이전트가 나온다. plan은 요구사항을 평가하고, implement는 코드를 작성하고, check는 품질을 검증하고, debug는 버그를 정밀 수정하고, research는 읽기 전용 조사 역할을 맡는다. (docs.trytrellis.app)

이건 단순 역할 분담이 아니다.
AI에게 “너는 지금 무엇을 해도 되고 무엇을 하면 안 되는지”를 명확히 제한하는 것이다.

특히 implement 에이전트는 Git commit이 금지되고, check 에이전트는 self-fix 후 Ralph Loop의 통제를 받는다고 문서가 설명한다. 이런 경계가 있어야 AI가 과하게 행동하지 않는다. (docs.trytrellis.app)

실제 사용 흐름을 개발자 관점에서 풀어보면

예를 들어 팀이 로그인 기능을 추가한다고 해보자.

1단계: Trellis 초기화

npm install -g @mindfoldhq/trellis@latest
trellis init --cursor --codex -u minsu

이러면 공통 .trellis/ 구조와 Cursor/Codex용 설정 파일이 함께 준비된다. (GitHub)

2단계: 프로젝트 규칙 작성

# .trellis/spec/backend/error-handling.md

- 서비스 레이어에서는 도메인 예외를 사용한다
- 컨트롤러에서는 HTTP 예외로 변환한다
- 모든 에러 응답은 code/message/requestId를 포함한다

이 파일은 이제 그냥 문서가 아니라, AI가 따라야 할 프로젝트 룰이 된다.

3단계: 작업 생성

./.trellis/scripts/task.py create "Add user login" \
  --slug user-login \
  --assignee minsu \
  --priority P1

4단계: AI 세션 시작

Claude Code라면 훅이 자동으로 문맥을 넣고, Cursor라면 /start 계열 명령을 통해 시작한다. 세션은 workflow, spec index, active tasks, 개발자 workspace를 읽고 현재 상황을 정리한다. (docs.trytrellis.app)

5단계: 구현과 검증

Implement Agent는 관련 spec과 코드 패턴을 읽고 구현한다.
Check Agent는 검증을 수행하고, Claude Code에서는 Ralph Loop가 lint/typecheck/test를 반복적으로 확인한다. (docs.trytrellis.app)

6단계: 세션 기록

작업 종료 후 세션은 기록되고, 다음 날 열었을 때 다시 맥락을 이어받을 수 있다. 이것이 Trellis가 말하는 project memory다. (GitHub)

Trellis를 언제 쓰면 좋을까

이 프로젝트는 모든 개발자에게 필요한 도구는 아니다.

다음 상황이면 꽤 잘 맞는다.

팀이 AI 코딩 도구를 혼용할 때

Claude Code만 쓰는 팀보다, Claude Code와 Cursor와 Codex가 섞여 있는 팀에서 가치가 더 크다. Trellis의 강점은 모델 성능이 아니라 워크플로 표준화이기 때문이다. (GitHub)

작업 문맥이 자주 사라질 때

매번 “지난번에 어디까지 했더라?”가 반복된다면 tasks/와 workspace/ 개념이 도움이 된다. 특히 기능 단위 PRD와 개발 저널을 남기고 싶은 팀에 적합하다. (docs.trytrellis.app)

AI 결과물을 검증 가능한 파이프라인에 넣고 싶을 때

AI가 만든 코드가 바로 merge되면 불안하다. 반대로 lint, typecheck, test 같은 검증 명령을 통과해야만 완료로 보게 만들고 싶다면 Ralph Loop 같은 개념이 유용하다. 다만 이 자동 루프는 문서상 Claude Code 중심 기능이고, 다른 플랫폼에서는 수동 명령 실행 비중이 더 크다. (docs.trytrellis.app)

멀티에이전트 병렬 개발을 진지하게 시도할 때

단일 브랜치에서 여러 AI를 돌리다 보면 금방 엉킨다. Git worktree 기반 분리는 실전적인 접근이다. 병렬 작업이 많은 팀일수록 Trellis의 구조적 이점이 커진다. (GitHub)

이 프로젝트의 한계도 있다

좋은 점만 있는 건 아니다.

첫째, 초반 설정 비용이 있다.
spec, task, workflow를 제대로 쓰려면 결국 팀이 규칙을 문서화해야 한다. AI 도구를 “그냥 켜서 바로 쓰고 싶은” 팀에게는 무겁게 느껴질 수 있다. 문서도 specs를 비워둔 템플릿으로 시작한다고 설명한다. 즉 구조는 제공하지만 내용은 팀이 채워야 한다. (GitHub)

둘째, 플랫폼별 기능 차이가 있다.
문서상 자동 세션 주입, 서브에이전트 spec 주입, Ralph Loop 같은 기능은 Claude Code 쪽이 더 강하다. Cursor나 Codex에서는 동일한 철학을 유지하지만 수동 명령에 더 의존한다. 즉 완전한 추상화라기보다 공통 프레임워크 + 플랫폼별 편차에 가깝다. (docs.trytrellis.app)

셋째, 팀이 문맥 관리에 진지해야 효과가 난다.
Trellis는 프롬프트 해킹 도구가 아니라 운영 체계다. 운영 체계는 팀이 쓰지 않으면 아무 가치가 없다.

마무리

Trellis를 보고 나면 이 프로젝트를 “또 하나의 AI 개발 툴”로 보면 오해하기 쉽다.

이건 도구가 아니라 질서에 가깝다.

• 규칙은 spec/으로 나누고
• 작업은 tasks/로 남기고
• 개인 맥락은 workspace/에 축적하고
• 플랫폼별 차이는 훅과 명령으로 흡수하고
• 결과물은 검증 루프로 통제한다

결국 Trellis가 던지는 메시지는 꽤 선명하다.

AI가 개발을 대신하는 시대가 아니라, AI가 팀의 개발 시스템 안으로 들어와야 하는 시대다.

그 관점에서 보면 Trellis는 꽤 영리하다.
모델을 바꾸는 대신, 프로젝트가 AI를 다루는 방식을 바꾼다.
그리고 바로 그 점이 이 오픈소스를 흥미롭게 만든다. (GitHub)