Project Report: agentfiles
Analysis Context
- Agent: Claude Code (claude-opus-4-6)
- Project: agentfiles (AI 에이전트 설정 관리 GUI)
- Privacy level: Full (공개 오픈소스)
- Commits reviewed: 30+ (최근 3개월)
- Sessions analyzed: 85
- Period: 2026-02 ~ 2026-03
- Confidence: High
Project Overview
AI 에이전트(Claude Code, Codex, Cursor 등)의 설정 파일을 시각적으로 관리하는 데스크톱 웹 앱입니다. ~/.claude/, ~/.codex/ 등 에이전트 설정 디렉토리를 탐색하고, skills, hooks, MCP servers, agents, plugins, commands 등 7가지 엔티티 타입을 대시보드에서 CRUD 관리합니다. npx agentfiles 한 줄로 실행 가능한 CLI 도구로 npm에 공개되어 있습니다.
Tech Stack: React 19, TypeScript, TanStack Start/Router/Query, Vite 7, shadcn/ui, Tailwind CSS v4, esbuild, Vitest
Public repo: github.com/ohing504/agentfiles
User's Role & Contributions
Youngsup은 이 프로젝트의 창시자이자 유일한 개발자입니다. 아이디어 구상부터 아키텍처 설계, 구현, 테스트, npm 배포, CI/CD 파이프라인 구축, 오픈소스 런칭까지 전체 생명주기를 담당했습니다. Phase 1-13에 걸쳐 체계적으로 개발을 진행했으며, v1 완성 후 v2 보드 스타일 대시보드로 대규모 리디자인을 수행했습니다.
Technical Decisions
| Decision | Chosen Approach | Reasoning | Alternatives Considered |
|---|---|---|---|
| 프레임워크 | TanStack Start + React 19 | 서버 함수 + 파일 시스템 접근이 필요한 데스크톱 도구 | Next.js (과도함), Electron (무거움) |
| UI 구조 | Notion 보드 스타일 대시보드 | Scope(User/Project) 행 + 엔티티 컬럼의 2차원 배치가 직관적 | 그리드 레이아웃 (v1, 이후 폐기) |
| 엔티티 관리 | EntityConfig |
7개 엔티티의 중복 컴포넌트를 통합 | 엔티티별 개별 컴포넌트 유지 |
| 디렉토리 구조 | Flat 구조 | 앱 규모 대비 features/ 기반이 과도 | Feature-based 구조 (v1, 이후 해체) |
| 빌드 | Vite(웹) + esbuild(CLI) 이중 빌드 | 웹앱은 Nitro, CLI 진입점은 경량 번들 | 단일 빌드 |
| 배포 | npm publish + release-please | Conventional Commits 기반 자동 릴리즈 | 수동 버전 관리 |
Notable Problem-Solving
엔티티 시스템 아키텍처 재설계. 7개 엔티티 타입이 각각 별도 리스트/상세 패널을 가져 다수의 컴포넌트가 중복되는 문제를 해결. shadcn 스타일 compound components를 만들고, EntityConfig<T> 제네릭 설정 객체로 엔티티별 차이를 선언적으로 정의. 레거시 에디터 라우트 전체를 대시보드로 병합하고 features/ 디렉토리를 해체했습니다.
v1 → v2 대시보드 전면 리디자인. v1의 단순 그리드 레이아웃에서 Notion 보드 스타일로 전면 전환. Scope 행이 전체 너비를 차지하고, 행 안에 엔티티별 카드가 수평 배치되는 구조. Sticky 헤더, visibility 토글, 드래그 리오더, 테마 토글까지 포함하며 기존 레거시 컴포넌트를 전면 삭제했습니다.
CI/CD 파이프라인 자동화. 3개 GitHub Actions 워크플로우를 구축. PR에서 lint/typecheck/test/build를 자동 실행하고, release-please로 버전 범프 + CHANGELOG 자동 생성, 태그 시 npm publish까지 완전 자동화했습니다.
설계 문서의 라이프사이클 관리. docs/plans/에 날짜별 설계 문서가 쌓이는 문제를 인식하고, 완료된 문서는 archive/로 이동, 현재 설계 문서만 활성 유지하는 정리 체계를 도입했습니다.
Characteristics Revealed
이 프로젝트에서 가장 두드러지는 특성은 "자신이 쓰는 도구를 직접 만드는" 빌더 정신입니다. AI 에이전트 설정 파일이 여러 디렉토리에 흩어져 관리가 어렵다는 자신의 문제를 해결하기 위해 앱을 만들고, npm에 공개하고, CI/CD까지 구축했습니다.
또한 과감한 구조 변경 능력이 돋보입니다. v1에서 열심히 만든 features/ 구조를 "앱 규모 대비 과도하다"고 판단하여 전면 해체하고, 중복 컴포넌트를 제네릭 시스템으로 통합한 것은 sunk cost에 얽매이지 않는 판단력을 보여줍니다.
UI 컴포넌트 재사용에 대한 엄격한 규칙도 특징적입니다. "새 컴포넌트 만들기 전에 반드시 기존 컴포넌트를 먼저 확인할 것", "엔티티 아이콘은 사이드바와 반드시 동일해야 함"처럼 일관성을 유지하기 위한 구체적 규칙을 에이전트에게 설정합니다.
Git & GitHub Analysis
- Commit style: 한글 + 영문 혼용 Conventional Commits. feat/fix/refactor/chore/ci/docs 접두사 일관 사용. PR 기반 워크플로우
- PR patterns: 다수의 PR을 평균 빠른 머지로 관리. 기능별 분리가 잘 되어 있음
- CI/CD engagement: 자체 구축한 CI에서 lint/typecheck/test/build 자동 실행. release-please로 버전 관리 자동화
- Code quality signals: 단위/통합/E2E 테스트, 엄격한 컴포넌트 규칙, 공통 상수 패턴
Summary
agentfiles는 Youngsup의 "도구를 만드는 사람" 성향이 가장 순수하게 발현된 프로젝트입니다. 자신의 문제를 해결하기 위해 시작하여, 13개 Phase를 거쳐 v1을 완성하고, v2로 대시보드를 전면 리디자인하고, 엔티티 시스템으로 코드 중복을 제거하는 과정에서 — 설계 우선 접근, 과감한 구조 변경, 그리고 sunk cost에 얽매이지 않는 판단력이 일관되게 나타납니다. 약 3주 만에 아이디어에서 npm 공개까지 완료한 실행력도 주목할 만합니다.