11개 작업영역을 한 장으로 연결했다: 삭제 0건 AI 워크스페이스 정리기

📝 한줄 요약

여러 AI 에이전트와 프로젝트가 제각각 잘 돌아가고 있었지만, 전체 상태를 한눈에 볼 방법은 없었습니다. Hermes Agent와 함께 기존 정본은 그대로 둔 채 얇은 관제층을 만들고, 자동수정하지 않는 Workspace Doctor를 붙였습니다. 홈 폴더의 파일 16개도 출처와 연결관계를 확인한 뒤 정리했습니다. 삭제한 파일은 0개였습니다.

바쁘시면 이것만 읽어도 돼요:

• 11개 작업영역을 workspace-registry.yml과 ACTIVE.md라는 하나의 진입점으로 연결했습니다.

• 홈 폴더에 보이던 일반 파일은 16개에서 0개가 됐지만, 파일을 삭제하지는 않았습니다.

• Workspace Doctor는 경로와 마운트, 정본, handoff, hash 상태 등 70개 항목을 읽기 전용으로 검사합니다.

• 최종 검사에서 DRIFT와 BLOCKED는 모두 0건이었습니다. 오래된 스냅샷 1건은 STALE로 남겨 문제를 숨기지 않았습니다.

• 가장 크게 배운 것은 이것입니다. 정리는 파일을 옮기는 일이 아니라 연결관계를 이해하는 일이었습니다.

🎯 이런 분들께 도움돼요

• 여러 AI 에이전트와 프로젝트를 동시에 운영하는 분

• 대화와 파일이 쌓여 어디에 무엇이 있는지 자꾸 다시 찾는 분

• AI에게 파일 정리를 맡기고 싶지만, 잘못된 이동이나 삭제가 걱정되는 분

• 개인 지식관리 시스템의 노트, 첨부파일, archive를 안전하게 정리하고 싶은 분

😫 문제 상황

제 AI 작업환경에는 이미 여러 전문 에이전트가 있었습니다. 문서 변환, 법률 검토, 강의 정리, 이미지 작업, 투자 분석처럼 역할도 나뉘어 있었습니다. 프로젝트별 저장소와 공유 폴더, 외부 볼륨, 배포 저장소도 각각의 규칙에 따라 운영되고 있었습니다.

문제는 각 부분이 아니라 전체였습니다.

작업을 다시 시작할 때마다 대화 기록을 찾고, 에이전트의 기억을 더듬고, 프로젝트마다 흩어진 handoff를 다시 확인해야 했습니다. 어떤 경로가 정본인지, 지금 무엇이 진행 중인지, 오래된 상태표를 현재 상태로 믿어도 되는지 한눈에 알기 어려웠습니다. 정확히 몇 분이 들었는지는 재지 않았지만, 같은 맥락을 반복해서 찾는 피로는 분명했습니다.

홈 폴더에 놓인 파일들도 신경 쓰였습니다. 겉보기에는 임시파일 같았지만 실제 프로그램이 사용하는 설정일 수도 있었습니다. AI에게 "깔끔하게 정리해줘"라고 말하면 금방 끝날 것 같았습니다. 동시에 그 한마디가 중요한 파일을 엉뚱한 곳으로 옮기거나 지우는 출발점이 될 수도 있었습니다.

기존에는 대화 기록과 에이전트 기억에 많이 의존했습니다. 하지만 기억은 현재 상태 그 자체가 아닙니다. 어제 맞았던 경로가 오늘도 맞는지, 오래된 스냅샷이 실제 작업 상태를 반영하는지 보장하지 못했습니다.

🌱 처음에는 무엇을 몰랐나

처음에는 워크스페이스를 정리하려면 폴더 구조부터 다시 짜야 한다고 생각하기 쉬웠습니다. 여러 프로젝트를 한곳으로 모으고 이름을 통일하면 깔끔해 보일 테니까요.

막상 들여다보니 그렇게 단순하지 않았습니다. 각 저장소는 이미 나름의 정본과 작업대, 배포 경로를 갖고 있었습니다. 법률자료의 원본과 가공본, 강의 결과물과 사람용 보관소, 장기 작업 registry는 서로 역할이 달랐습니다. 이들을 한 폴더 아래로 옮기면 겉은 단정해져도 정본 경계가 무너질 수 있었습니다.

두려운 지점도 세 가지였습니다.

첫째, AI가 파일을 잘못 이동하거나 삭제할 수 있다는 점. 둘째, 여러 전문 에이전트와 저장소를 어떤 기준으로 묶어야 할지 모른다는 점. 셋째, 오래된 로그와 현재 상태를 구분하기 어렵다는 점이었습니다.

그래서 AI에게 정답을 바로 실행하게 하지 않았습니다. 먼저 조사하고, 계획을 분리하고, 제가 승인한 뒤 실행하고, 마지막에 다시 검증하는 순서로 일을 나눴습니다.

🛠️ 사용한 도구

• Hermes Agent: 파일 조사, 구조 설계, 문서 생성, 검증 실행

• 타디스: 전체 좌표를 연결하고 전문 작업영역을 조율하는 오케스트레이터

• Markdown·YAML·JSON: 사람이 읽는 상태판과 기계가 읽는 registry·inventory

• SHA-256: 파일 이동 전후 동일성 확인

• Workspace Doctor: 경로·마운트·정본·handoff·freshness·hash 상태의 읽기 전용 진단

🔧 작업 과정

전체를 옮기지 말고 지도를 먼저 만들었다

첫 요청은 "새로운 워크스페이스 사례를 참고해 현재 환경의 개선점을 찾되, 실제 변경은 계획과 분리하자"는 취지였습니다.

[운영기록 기반 요청 요약]
현재 AI 워크스페이스의 개선점을 조사하되, 먼저 읽기 전용으로 분석하고 실제 변경은 별도로 결정한다.

Hermes Agent는 실제 작업 좌표를 조사했습니다. 공용 운영문서, 장기 작업 registry, 지식 저장소, 강의 결과물 보관소, 웹 배포 저장소, 공유 볼륨까지 확인했습니다. 그 결과 11개 핵심 작업영역을 정본 경로, 담당 에이전트, 입출력, 민감도, 품질 기준으로 정리했습니다.

여기서 중요한 결정을 내렸습니다. 기존 프로젝트를 새 워크스페이스 안으로 옮기지 않기로 했습니다. 대신 새 관제층에는 실제 자료가 아니라 연결 정보만 두었습니다.

• workspace-registry.yml에는 기계가 읽을 수 있는 정본과 담당, 상태를 적었습니다.

• ACTIVE.md에는 사람이 지금 상태와 다음 행동을 한 장에서 볼 수 있게 했습니다.

• source-of-truth-map.md에는 각 저장소가 어떤 역할을 하는지 정리했습니다.

• Decision Record에는 왜 기존 정본을 옮기지 않았는지 남겼습니다.

흩어져 있던 11개 작업영역이 이 두 문서에서 하나의 시스템처럼 보이기 시작했습니다. 이때 "이 방식이 통한다"는 느낌이 왔습니다. 폴더를 합치지 않았는데도 전체가 연결됐습니다.

대화 기억 대신 현재 상태를 남겼다

Devlog는 무엇을 했는지 기록하는 데 좋습니다. 하지만 시간이 지나면 어떤 결정이 아직 유효한지, 왜 그 방식을 선택했는지 찾기 어렵습니다.

그래서 활동 기록과 운영 결정을 분리했습니다. handoff에는 현재 상태, 마지막 완료 지점, 다음 행동, 정본 경로를 담았습니다. 오래된 handoff는 지우지 않고 archive로 보냈습니다. 장기 정책은 Decision Record에 남겼습니다.

이 과정에서 신뢰 기준도 달라졌습니다. "에이전트가 기억하고 있다"보다 "현재 상태가 파일로 적혀 있고 다시 검증된다"를 더 믿게 됐습니다.

고치지 않는 Doctor를 만들었다

다음 단계는 Workspace Doctor였습니다.

[운영기록 기반 요청 요약]
경로와 마운트, handoff, 정본과 hash 상태를 통합 검사하되 결과를 근거로 자동수정하지 않는다.

Doctor는 70개 항목을 검사합니다. 필수 경로가 있는지, 외부 볼륨이 연결됐는지, 정본이 겹치지 않는지, handoff가 오래되지 않았는지, inventory의 hash가 달라지지 않았는지 확인합니다.

처음부터 자동수정 기능은 넣지 않았습니다. Doctor의 역할은 진단과 근거 제시입니다. 실제 이동이나 설정 변경은 사람이 보고 결정합니다.

검사 결과 오래된 작업 상태 스냅샷 1건이 STALE로 잡혔습니다. 이 경고를 억지로 없애지 않았습니다. 현재 상태로 믿으면 안 되는 파일이라는 사실을 그대로 남겼습니다. 반면 정본 불일치를 뜻하는 DRIFT와 필수 구조 부재를 뜻하는 BLOCKED는 0건이었습니다.

같은 상태에서 연속 실행했을 때 생성 시각을 제외한 결과도 같았습니다. 진단기가 그때그때 다른 말을 하지 않는다는 점까지 확인했습니다.

가장 조심스러웠던 파일 하나

홈 폴더 파일을 정리할 때 가장 조심스러웠던 것은 mineru.json이었습니다. 이름만 보면 도구가 남긴 설정 부산물처럼 보였습니다. 그냥 다른 폴더로 옮길 수도 있었습니다.

하지만 관련 소스코드와 프로그램의 공식 동작을 확인하니 이 파일은 활성 설정이었습니다. 기본 동작에서는 홈 경로의 파일을 직접 읽고 있었습니다. 이걸 모르고 옮겼다면 다음 실행부터 설정을 찾지 못했을 수 있습니다.

그래서 설정 본체는 표준 config 영역으로 옮기되, 기존 경로에는 호환 링크를 남겼습니다. 실제 MinerU 실행환경에서 새 설정을 읽는지도 시험했습니다.

이 장면에서 배운 원칙은 단순합니다. 파일명이나 겉모습으로 용도를 추측하지 않는다. 관련 소스코드와 실제 동작을 확인한다.

전환점: 정리는 연결관계를 이해하는 일이었다

홈 폴더의 다른 파일에도 같은 원칙을 적용했습니다.

[운영기록 기반 요청 요약]
파일의 출처와 참조, hash와 rollback 경로를 확인하고 승인 후 정리한다.

먼저 16개 파일의 inventory와 SHA-256을 만들었습니다. 다른 프로젝트에서 참조하는지 검색했습니다. 동일한 정본이 있는 문서는 크기와 hash, 본문까지 비교했습니다. 이동 대상과 이유를 표로 만들고 승인을 받은 뒤 움직였습니다.

실행 중 하나라도 실패하면 이미 옮긴 파일을 원위치로 돌리도록 했습니다. 이동 후에는 hash를 다시 계산했습니다. rollback 경로도 migration manifest에 남겼습니다.

결과적으로 홈 폴더에 보이던 일반 파일은 16개에서 0개가 됐습니다. 삭제한 파일은 없었습니다. 필요한 설정은 계속 작동했고, 검토가 필요한 파일은 격리 폴더에서 보존됐습니다.

그때 정리에 대한 생각이 바뀌었습니다.

정리는 파일을 옮기는 일이 아니라 연결관계를 이해하는 일이었다.

✅ 결과

Before vs After

결과물

• 전체 정본과 담당을 기록한 registry

• 현재 상태와 다음 행동을 보여주는 ACTIVE 관제판

• 결정 이유를 남기는 Decision Record

• 활성 handoff와 archive 구조

• 자동수정하지 않는 Workspace Doctor

• 홈 파일 inventory와 이동·rollback manifest

• 계획부터 실행과 검증을 이어 쓴 workspace Devlog

추천 이미지: 이 섹션 아래에 HEALTH.md의 Doctor 요약 화면을 넣으면 좋습니다. PASS 62, WARN 7, STALE 1, DRIFT 0, BLOCKED 0이 한 화면에 보이는 부분이 적합합니다. 공개 전 실제 사용자 경로는 가립니다.

아직 첫날이다

구조적 검증은 끝났지만 장기 사용 효과까지 증명된 것은 아닙니다. 이 시스템은 구축 첫날입니다. 실제로 재진입 피로가 얼마나 줄어드는지, 경고가 얼마나 정확한지, 운영하면서 문서가 오래되지 않는지는 몇 주 더 지켜봐야 합니다.

이 점을 숨기지 않는 것도 이번 운영 방식의 일부입니다. 통과한 항목과 아직 관찰이 필요한 항목을 나눠 기록합니다.

내가 달라진 점

이전에는 AI에게 "정리해줘"라고 한 번에 맡길 가능성이 컸습니다. 지금은 일을 조사, 계획, 승인, 실행, 검증으로 나눕니다.

에이전트의 기억보다 현재 상태를 보여주는 registry와 ACTIVE를 더 신뢰하게 됐습니다. AI의 역할도 다르게 보게 됐습니다. AI는 파일을 빨리 처리하는 실행자일 뿐 아니라, 여러 작업영역을 연결하고 상태를 점검하는 오케스트레이터가 될 수 있었습니다. 단, 실행 권한보다 먼저 관찰 규칙과 중단선을 줘야 했습니다.

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 폴더를 옮기기 전에 정본, 담당, 입력, 출력부터 지도에 적었습니다.

2. 대화 기록과 기억 대신 현재 상태를 보여주는 ACTIVE 문서를 만들었습니다.

3. AI가 바로 고치지 못하게 하고, 읽기 전용 진단 뒤에 사람의 승인을 두었습니다.

4. 파일 이동은 참조 검색, hash, rollback, 실제 프로그램 read-back까지 확인했습니다.

5. 경고를 없애는 것보다 경고가 무엇을 뜻하는지 정확히 남겼습니다.

이렇게 하면 위험해요

1. 파일 이름만 보고 임시파일이라고 단정하기

2. 오래된 상태표를 현재 실행 상태로 믿기

3. 여러 정본을 새 폴더로 한꺼번에 옮기기

4. "정리"와 "삭제"를 같은 일로 취급하기

5. 파일이 새 위치에 존재한다는 이유만으로 완료했다고 판단하기

🌍 다른 업무에 적용한다면

개인 지식관리 시스템에도 같은 방식을 적용할 수 있습니다.

노트 앱을 오래 쓰면 본문, 첨부파일, 내보낸 PDF, 임시 OCR 결과, archive가 섞입니다. 이때 폴더부터 다시 나누기보다 먼저 각 자료의 역할을 적습니다. 어떤 노트가 정본인지, 첨부파일은 어디에서 참조되는지, archive는 검색돼야 하는지, 중복 파일의 내용이 정말 같은지 확인합니다.

그다음 읽기 전용 Doctor가 끊어진 첨부파일, 오래된 index, 중복 정본 후보를 보고하게 합니다. 이동은 사람이 승인하고, 전후 hash와 링크를 확인합니다. 워크스페이스 정리에서 사용한 원칙이 그대로 적용됩니다.

🤝 배워서 남 주기

실제 개인 경로와 내부 저장소 이름은 공개하지 않습니다. 대신 다른 사람이 자기 환경에 바꿔 쓸 수 있는 세 가지를 나누려고 합니다.

• 정본과 담당을 찾는 질문 순서

• ACTIVE와 registry의 최소 필드

• 읽기 전용 Doctor의 상태 체계

• 파일 이동 전 참조·hash·rollback 체크리스트

• 아래의 재사용 프롬프트 세 가지

성공한 폴더 구조를 그대로 복사하게 하는 것보다, 자기 환경의 연결관계를 먼저 조사하게 만드는 편이 안전합니다.

🕊️ 널리 사람을 이롭게 한다면

AI 초보자는 파일을 잘못 건드릴까 봐 정리를 미루기 쉽습니다. 프로젝트가 많아진 사람은 매번 같은 경로와 맥락을 다시 찾습니다. 여러 에이전트를 운영하는 사람에게는 누가 무엇을 책임지고, 어떤 문서가 현재 상태인지 판단할 공통 기준이 필요합니다.

이 사례가 줄이고 싶은 것은 그 세 가지입니다. 파일 손상에 대한 불안, 반복 탐색의 피로, 안전한 협업 기준의 부재입니다.

AI가 더 많은 일을 하게 될수록 "무엇을 할 수 있는가"만큼 "어디까지 자동으로 하지 않을 것인가"가 중요해집니다. 읽기 전용 진단, 사용자 승인, hash와 rollback은 화려하지 않지만 누구나 재사용할 수 있는 안전장치입니다.

🚀 앞으로의 계획

먼저 STALE로 남은 작업 상태 스냅샷의 생성 경로를 조사해 현재 상태와 맞추려고 합니다. 그다음 정상 상태에서는 조용하고 이상이 있을 때만 알리는 alert-only 점검을 수동으로 검증할 계획입니다.

이후 몇 주 동안 실제로 사용하며 재진입 피로와 경고 정확도를 관찰합니다. 충분한 근거가 쌓이면 관제 구조, Doctor, 안전 정리 절차를 재사용 가능한 스킬과 템플릿으로 다듬을 생각입니다.

📋 재사용 가능한 프롬프트

프롬프트 1: 워크스페이스 정본 지도 만들기

내 작업환경의 폴더를 바로 이동하거나 이름을 바꾸지 말고 먼저 읽기 전용으로 조사해줘. [조사할 루트 경로] 아래의 주요 프로젝트마다 정본 경로, 담당자 또는 담당 에이전트, 입력 위치, 최종 산출물 위치, 배포 위치, 품질 확인 방법, 최신 handoff, 현재 상태를 표로 정리해줘. 정본이 둘 이상이거나 확실하지 않으면 추측하지 말고 conflict 또는 unknown으로 표시해줘. 조사 결과를 바탕으로 기존 자료를 옮기지 않는 얇은 registry와 ACTIVE 상태판을 제안해줘. 실제 파일 이동과 설정 변경은 하지 마.

프롬프트 2: 홈 폴더 파일을 안전하게 정리하기

[정리 대상 폴더]의 파일을 이름만 보고 삭제하거나 이동하지 마. 먼저 파일별 크기, 생성·수정 시각, SHA-256, 관련 프로젝트, 참조 경로, 동일 내용의 정본 존재 여부, 활성 설정 여부를 조사해줘. 각 파일을 유지, 정본 편입, 검토 격리, 설정 위치 이전 후보로 분류하고 이유와 제안 경로를 표로 만들어줘. 내가 승인하기 전에는 변경하지 마. 승인 후 이동할 때는 대상 충돌을 확인하고, 이동 전후 hash를 비교하고, 실패 시 원위치로 복구하며, rollback manifest를 남겨줘. 삭제는 별도 승인 없이는 하지 마.

프롬프트 3: 자동수정 없는 Workspace Doctor 설계하기

[워크스페이스 registry 경로]를 기준으로 경로 존재, 외부 볼륨 마운트, 정본 중복, stale handoff, 오래된 상태 스냅샷, 끊어진 링크, inventory hash drift를 검사하는 읽기 전용 Doctor를 설계해줘. 상태는 PASS, WARN, STALE, UNKNOWN, DRIFT, BLOCKED로 구분하고 모든 경고에 근거 경로를 표시해줘. Doctor는 파일 이동, 삭제, 설정 변경, Git 정리를 자동으로 수행하면 안 돼. 같은 상태에서 두 번 실행했을 때 생성 시각을 제외한 결과가 같은지 검증하고, 사람이 읽는 HEALTH 보고서와 기계가 읽는 JSON 결과를 함께 만들 수 있게 해줘.

이 작업에서 가장 만족스러웠던 결과는 홈 폴더가 비었다는 사실만은 아니었습니다. 왜 그 파일이 그 자리에 있었는지, 옮겨도 되는지, 옮긴 뒤 무엇을 확인해야 하는지 설명할 수 있게 된 것이 더 컸습니다.

정리는 삭제의 다른 이름이 아니었습니다. 연결을 이해하고, 현재 상태를 기록하고, 되돌릴 수 있게 움직이는 일이었습니다.