Smart Folder Organizer API 설계

파일 정리를 잘 못 한다, 정확히는, 할 시간이 없다. 다운로드 폴더에 파일이 쌓이고, 바탕화면에도 쌓인다. 필요할 때마다 “그거 어디 있더라”를 반복한다.

그러다 바이브코딩으로 개발한 것이 smart-folder-organizer였다.
AI가 파일을 분석해서 폴더 구조를 제안해주는 웹앱이다. Claude한테 요구사항을 계속 던지면서 같이 만들었다.

---

전체 구조

smart-folder-organizer/
├── app/
│   ├── page.tsx              # 메인 페이지 (6단계 스텝)
│   └── api/
│       ├── scan/route.ts     # 폴더 스캔
│       ├── analyze/route.ts  # AI 분석 (Claude or 사내 LLM)
│       ├── apply/route.ts    # 실제 파일 이동
│       └── undo/route.ts     # 작업 취소
├── components/
│   └── steps/                # 각 단계별 UI
└── lib/
    ├── types.ts
    └── utils.ts

Next.js 14 기반이다. 프론트 + API + 파일시스템을 한 프로젝트에서 처리할 수 있어서 로컬 도구에 맞았다.

 

핵심 1: 파일 스캔

웹에서는 불가능한 부분이다. 로컬이니까 Node.js fs 모듈로 직접 디렉토리를 읽는다.

function scanDirectory(dirPath: string) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });

  for (const entry of entries) {
    if (shouldExclude(entry.name)) continue;

    if (entry.isFile()) {
      const ext = path.extname(entry.name);

      if (TEXT_EXTENSIONS.has(ext)) {
        file.preview = getTextPreview(fullPath);
      }

      files.push(file);
    }
  }
}

node_modules, .git, .DS_Store 같은 건 자동으로 걸러낸다. 최대 깊이, 최대 파일 수도 슬라이더로 조절할 수 있게 했다.

텍스트 파일은 일부 내용을 같이 넘겼다. 파일명만 넣었을 때보다 결과가 훨씬 안정적이었다.

핵심 2: AI 분석

파일 목록을 그대로 넘기면 안 된다. 형식을 강제해야 한다.

const prompt = `
파일 정리 전문가입니다.

파일 목록:
${fileList}

JSON으로만 응답:

{
  "summary": "...",
  "folder_structure": [...],
  "classifications": [...]
}
`;

이 부분에서 제일 많이 깨졌다.

• 마크다운 섞임
• 설명 텍스트 추가됨
• JSON 깨짐

결국 해결 방법은 단순했다. “출력 형식을 강제한다” 페르소나도 같이 넣었다.

• 개발자 → 코드 중심 구조
• 컨설턴트 → 프로젝트 / 날짜 구조

이건 생각보다 퍼포먼스가 괜찮았다.

핵심 3: 실제 파일 이동

Anthropic 계정이 없어도 쓸 수 있게 커스텀 엔드포인트를 지원했다.

for (const op of operations) {
  const dir = path.dirname(op.to);

  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }

  fs.renameSync(op.from, op.to);
}

UI 첫 화면에서 Claude AI / 사내 LLM 중 선택하면 된다. URL이랑 Bearer 토큰만 넣으면 그 이후는 똑같이 동작한다.

 

중요한 건 두 가지였다.

1. 폴더 자동 생성 

2. 드라이런

if (dryRun) return operations;

이건 필수다. 실수 한 번이면 파일 다 꼬인다.

핵심 4: Undo

실제로 파일을 이동하는 기능이 생기면 반드시 필요한 게 복구다. 적용할 때마다 작업 기록을 JSON으로 저장해둔다.

const batch: OperationBatch = {
  id: generateId(),
  timestamp: new Date().toISOString(),
  basePath,
  operations,  // [{from: "원래 경로", to: "이동된 경로", type: "move"}]
  label: "파일 정리 - 2026.03.22",
};

// ~/.smart-folder-organizer/history.json 에 저장
history.unshift(batch);
saveHistory(history.slice(0, 20)); // 최대 20개 유지
```

복구할 때는 `operations`를 역순으로 뒤집어서 그대로 되돌린다. 완료 화면에서 버튼 하나로 실행된다.

그대로 기록하고,

for (const op of reversed) {
  fs.renameSync(op.to, op.from);
}

역순으로 돌리면 복구된다. DB는 안 썼다. JSON 파일 하나로 충분했다.

사용 흐름

1. API 설정    →  Claude AI 또는 사내 LLM 선택
2. 페르소나    →  개발자 / 디자이너 / 컨설턴트 등 프리셋 선택
3. 파일 스캔   →  정리할 폴더 경로 입력
4. AI 분석     →  Claude가 폴더 구조 + 파일 분류 자동 제안
5. 미리보기    →  마음에 안 들면 파일별로 수동 변경 가능
6. 적용        →  실제 파일 이동 (드라이런으로 먼저 확인 권장)
```

여기서 중요한 건 미리보기다. AI가 항상 맞지는 않는다.
특히 파일명만 보고는 틀리는 경우가 많다. 그래서 수동으로 수정할 수 있게 했다.

실행 방법

1. Node.js 설치 (nodejs.org → LTS 버전)
2. zip 압축 해제
3. 폴더 주소창에 cmd 입력 (PowerShell 아님 - 보안 오류 남)
4. npm install
5. npm run dev
6. http://localhost:3000 접속

PowerShell(파란 창)은 스크립트 보안 설정 때문에 npm이 안 돌아간다. 반드시 cmd(검은 창)를 써야 한다.

 

마치며

처음엔 "AI한테 파일 정리를 시킨다"는 아이디어가 좀 거창하게 느껴졌다. 막상 만들어보니 핵심은 단순했다.

파일 목록을 잘 정리해서 넘기고, JSON으로 받아서 파일시스템에 적용하면 된다.

AI가 판단하고, 사람이 검토하고, 실제 이동은 코드가 한다. 각자 역할이 명확하다.

개발자가 아니어도 Claude한테 요구사항을 설명하면 이 정도 도구는 충분히 만들 수 있다는 것도 확인했다. 

파일을 모으고 AI로 분류하고 코드로 실행한다 입력 → 분석 → 검토 → 실행 → 복구

https://github.com/rootofdata/v0-smart-folder-organizer

GitHub - rootofdata/v0-smart-folder-organizer