이런 분께
AI와 여러 날 작업한 뒤 무엇이 현재 상태인지 다시 찾느라 시간을 쓰는 분
Plan, 작업 일지, 완료 근거가 있는데도 서로 다른 상태를 가리키는 분
끝난 프로젝트를 지우자니 불안하고 그대로 두자니 현재 작업과 섞이는 분
특정 AI 제품에 묶이지 않는 Markdown·Git 기반 운영 규칙을 만들고 싶은 분
이 글은 완성된 프로젝트 관리 도구를 소개하는 글은 아닙니다. AI가 작업 상태를 추측하지 않도록, 사람이 이미 정한 경계를 파일과 작은 검사 규칙으로 남긴 과정에 가깝습니다.
현재 프로젝트 진행 상태를 알 수가 없었습니다.
최근에 여러 좋은 워크스페이스, AI 지식관리 체계 등 오픈 소스 레포 등을 참고하면서 조금씩 제 워크스페이스에 녹여보는 실험을 하고 있습니다. 23기 AI지식관리 스터디를 청강하면서 deck님의 akm repo의 좋은 부분도 쏙쏙 뽑아서 적용해보려고 테스트중입니다. Deck님의 AKM에 있는 learning loop와는 다르고 좀더 단순하지만, 다음과 같은 요구 사항에 맞게 project가 살아숨쉬게 하는 루프를 넣는 실험을 해보기로 했습니다.
우리 프로젝트 폴더에 이것저것 있는데,
이미 적용된 것은 치워도 되고 적용되지 않은 것만 남겨도 되지 않을까?겉으로는 폴더 정리 요청이었지만, 제가 원한 것은 단순한 청소가 아니었습니다. 어디까지 진행됐는지가 최신 상태로 유지되고, Plan(작업 계획), devlog(작업 일지), evidence(완료 근거) 같은 연결 문서도 함께 최신 상태를 가리키길 바랐습니다.
수명주기 규칙을 설계한 뒤 archive를 실행하기 직전, 약간 규칙없이 마구 만들어진 프로젝트 루트에는 11개 폴더가 있었습니다. 완료된 프로젝트와 진행 중인 프로젝트가 한곳에 섞여 있었습니다.
Before
10-projects/
├─ core-document-integrity/
├─ core-document-integrity-adoption/
├─ crawl4ai-skill/
├─ idea-inbox/
├─ lore-commits-skill/
├─ okf-knowledge-notes/
├─ project-lifecycle-governance/
├─ shared-harness-sync/
├─ user-context-architecture/
├─ workspace-contract-checker/
└─ workspace-restructure/
진행 중, 운영 정본 보유, 완료 기록이 모두 같은 깊이에 있었습니다.
폴더 이름만 봐서는 지금 작업해야 하는 프 로젝트인지, 기능은 이미 다른 곳에 적용됐고 실행 기록만 남은 프로젝트인지 알기 어려웠습니다. 저도 헷갈리는데 AI가 매번 정확히 구분하길 기대하기는 어려웠습니다.
그런데 완료 폴더를 전부 archive(보관 영역)로 옮기는 것도 정답은 아니었습니다. 어떤 프로젝트 안에는 현재 검사 도구가 직접 참조하는 결정 문서가 남아 있었습니다. 폴더를 깔끔하게 만들겠다고 이를 숨기면, 오히려 운영 중인 정본이 과거 기록 속에 묻힐 수 있었습니다.
이때부터 문제를 “어떤 폴더를 만들까”가 아니라 “작업의 시작과 끝에서 누가 어떤 판단을 맡을까”로 바꾸어 보기 시작했습니다.
어디에 둘지는 workspace-governance가 맡았습니다
첫 번째 역할은 workspace-governance였습니다. 이름은 거창하지만, 쉽게 말하면 파일과 폴더의 소유권을 정하는 작업 절차입니다. 여기서 스킬은 특정 AI에게 반복해서 적용할 수 있도록 Markdown으로 적어둔 작업 절차를 뜻합니다.
이 스킬이 답하는 질문은 다음과 같습니다.
아직 실행을 약속하지 않은 생각은 어디에 둘 것인가?
목표와 완료 조건이 생긴 작업은 언제 프로젝트가 되는가?
여러 작업에서 다시 쓸 지식과 한 프로젝트의 판단 근거를 어떻게 나눌 것인가?
임시 파일을 지우기 전에 다른 문서가 그 파일을 유일한 근거로 참조하고 있지는 않은가?
중요했던 점은 새 중앙 규칙 폴더를 계속 늘리지 않는 것이었습니다. 항상 읽는 짧은 규칙 파일은 안전 불변조건과 안내만 맡고, 자세한 절차는 스킬과 각 영역의 README에 두었습니다. 한 규칙의 전문을 여러 곳에 복사하면 나중에는 어느 쪽이 최신인지 다시 판단해야 하기 때문입니다.
이 방식은 “어디에 둘지”에는 꽤 잘 답했습니다. 하지만 이미 변경한 이유는 여전히 대화 속에서 사라졌습니다. 다음 세션에서 Git 이력을 보면 무엇이 바뀌었는지는 알 수 있어도, 왜 다른 대안을 버렸는지는 알기 어려웠습니다.
그래서 두 번째 역할이 필요했습니다.
왜 그렇게 바꿨는지는 lore-commits가 맡았습니다
https://github.com/tmdgusya/lora/ -> 참고한 오픈 소스
기존에 에이전트한테 그냥 대충 작업 끝나면 커밋해달라고 했었는데, 조금더 체계적으로 기록을 남길 수 있을 것 같아 적용하였습니다.
lore-commits는 Git commit(변경 묶음을 저장하는 이력)에 결정 맥락을 짧게 남기는 절차입니다. 커밋 제목을 길게 쓰는 대신, 실제로 의미가 있는 항목만 trailer라는 꼬리표 형태로 붙입니다.
프로젝트 수명주기 규칙을 도입할 때 남긴 commit 내용을 줄이면 다음과 같습니다.
Constraint: archive 이동과 삭제는 자동화하지 않고
정확한 대상과 링크 수정 범위를 별도 승인받는다.
Rejected: 완료 프로젝트 일괄 archive
| 현재 운영 정본까지 숨은 운영 의존성으로 만들 수 있다.
Directive: retained는 허용 사유와 근거가 있을 때만 사용한다.
Tested: 38개 테스트, 문서 계약, 링크, Git diff 검사 통과.
Not-tested: 실제 프로젝트 이동과 이동 후 링크 변경.
여기서 중요한 것은 모든 커밋에 모든 항목을 채우지 않는다는 점입니다. 실제로 검토하지 않은 대안을 나중에 만들어 적지 않고, 실행하지 않은 테스트도 적지 않습니다. 단순한 오타 수정이라면 제목 한 줄이면 충분합니다.
이 규칙 덕분에 Plan과 별개로 그 변경 자체에 붙어 있어야 할 이유가 Git 이력에 남았습니다. Plan은 프로젝트 전체의 목표와 순서를 설명하고, commit은 특정 변경의 제약과 검증 경계를 설명합니다.
하지만 이 단계까지 와도 마지막 질문은 비어 있었습니다.
프로젝트가 끝난 뒤, 그 폴더는 언제 현재 영역에서 빠져나가야 할까?
파일의 위치와 변경 이유를 잘 기록해도, 끝내는 규칙이 없으면 프로젝트 루트는 다시 쌓이기 시작합니다.
새 project-lifecycle-management가 마지막 빈칸을 채웠습니다
그래서 새로 만든 것이 project-lifecycle-management였습니다. 이 스킬은 프로젝트를 세 상태로 나눕니다.
상태
뜻
active
열린 작업·관찰·승인이 남아 있음
retained
실행은 끝났지만 현재 운영 정본이나 유지보수 코드를 직접 소유함
archived
현재 운영 책임은 없고 실행 기록만 남음
처음에는 archive-ready를 네 번째 상태로 만들 생각도 했습니다. 하지만 외부 검토에서 “실행 상태와 이동 승인 상태가 섞인다”는 지적을 받았습니다. 결국 상태는 세 개만 두고, 실제 이동 승인만 남았다는 표시는 closure: ready라는 별도 값으로 분리했습니다.
status: done
lifecycle: active
closure: ready이 세 줄은 서로 다른 질문에 답합니다.
status: 작업 자체가 끝났는가?lifecycle: 이 프로젝트 폴더가 현재 어떤 책임을 지는가?closure: 보관 영역으로 옮길 준비가 끝났는가?
특히 retained를 “일단 남겨두자”는 주차장으로 쓰지 않도록 제한했습니다. 현재 운영 정본을 직접 소유하거나 실제 유지보수 대상이 있을 때만 허용하고, 그 근거 문서의 경로를 함께 적게 했습니다.
이 규칙에서 archive는 삭제가 아닙니다. 실행 기록을 현재 작업 목록에서 분리하는 것입니다. 반복해서 쓸 절차는 스킬로, 공용 검사 도구는 도구 영역으로, 재사용 지식은 참고 영역으로 먼저 승격합니다. 프로젝트 폴더에는 그 작업이 왜 필요했고 어떻게 검증했는지에 대한 역사만 남깁니다.
문서도 같은 종료 루프를 돌게 했습니다
폴더 상태만 바꾸면 Plan과 작업 기록이 다시 뒤처질 수 있습니다. 그래서 task ID와 완료 근거, 다음 세션 인계를 연결했습니다.
Before
Plan evidence handoff Git commit
각자 상태 별도 문서 기억나는 다음 일 변경 요약
└──────── 서로 다른 시점을 가리킬 수 있음 ────────┘
After
Plan의 영구 task ID
│
▼
실제 작업·테스트
│
├──── devlog에 세션별 수행 내용 기록
│
▼
completion evidence
(for_task + verification + completion claim)
│
▼
Plan task를 done으로 변경
│
▼
handoff가 아직 열린 task를 가리키는지 검사
│
▼
lore commit에 제약·기각 대안·실제 검증 기록
│
▼
active / retained / archived 판정
작은 Python 검사 도구도 붙였습니다. 완료로 표시한 task에 통과한 evidence가 없거나, 다음 세션 인계가 이미 끝난 task를 계속 가리키면 오류를 냅니다. devlog는 합격 여부를 결정하는 문서가 아니라 세션별로 무엇을 했는지 복원하는 기록으로 남기고, 종료 시 Plan·evidence·handoff와 함께 다시 봅니다. 이 규칙은 특정 AI 제품 기능이 아닙니다. Markdown과 Python 파일이므로 다른 AI나 사람이 같은 저장소를 읽고 검사 명령을 실행해도 동일하게 동작합니다.
다만 이 검사 도구는 evidence의 내용까지 진실이라고 보증하지는 않습니다. 테스트를 실제로 실행했는지, 결과를 과장하지 않았는지는 여전히 실행 로그와 사람의 검토가 담당합니다. 검사기는 문서끼리 명백히 모순되는 경우만 막습니다.
11개를 분류하고 8개를 실제로 옮겼습니다
처음에는 기존 프로젝트 11개를 읽기 전용으로 분류했습니다. Plan 상태, 열린 task, 다음 세션 인계, 적용된 산출물, 외부 문서의 참조를 함께 봤습니다.
첫 분류 결과는 다음과 같았습니다.
진행 책임이 남은
active: 3개운영 정본을 직접 소유한
retained: 1개이동 준비가 된
closure-ready: 7개
분류 직후 자동으로 옮기지는 않았습니다. 정확한 이동 목록과 수정할 링크를 먼저 확인하고, 승인받은 두 번의 batch로 이동했습니다. 수명주기 규칙을 만든 프로젝트 자체도 작업이 끝난 뒤 보관 대상이 되어 최종적으로 8개가 archive로 이동했습니다.
After
10-projects/
├─ core-document-integrity/ # retained: 현재 계약의 근거 보유
├─ shared-harness-sync/ # active 당시 기준
├─ user-context-architecture/ # active 당시 기준
└─ archive/
├─ core-document-integrity-adoption/
├─ crawl4ai-skill/
├─ idea-inbox/
├─ lore-commits-skill/
├─ okf-knowledge-notes/
├─ project-lifecycle-governance/
├─ workspace-contract-checker/
└─ workspace-restructure/
기술 검증에서는 38개 테스트, 폴더 계약 검사, 상대 링크 검사, project ID 중복 검사, Git diff 검사를 통과했습니다. archive 안의 문서를 현재 운영 정본으로 다시 참조하지 않는지도 확인했습니다.
그리고 workspace-governance, project-lifecycle-management, commit 규칙을 포함한 기본 운영 스킬을 공용 경로로 옮겼습니다. 여러 AI가 각자 다른 복제본을 읽지 않고 같은 스킬 원본을 읽도록 한 것입니다. 항상 읽는 규칙 파일은 상세 절차를 덜어내면서 109줄에서 최종 42줄까지 줄었습니다.
검증된 것은 구조이고, 체감 효과는 아직 관찰 중입니다
다만 여기서 “써보니 편해졌다”고 쓰면 과장입니다.
기존 프로젝트를 분류하고 8개를 archive로 옮기는 기술 검증은 끝났습니다. 문서 연결과 검사 도구도 통과했습니다. 하지만 새 프로젝트 하나가 시작부터 종료까지 이 루프를 자연스럽게 한 바퀴 돌았을 때, 제가 정말로 “이제 어디까지 했는지 바로 알겠다”고 체감할지는 아직 관찰하지 못했습니다.
따라서 지금 말할 수 있는 결과는 다음 정도입니다.
확인된 것
앞으로 확인할 것
완료·진행·운영 정본의 분류 규칙
새 프로젝트에서의 실제 사용 편의성
task ID와 evidence의 기계적 연결
기록 부담이 적절한지
8개 프로젝트의 승인형 archive
다음 세션 복원 시간이 실제로 줄어드는지
여러 AI가 읽는 공용 스킬 정본
맥북 환경에 이식했을 때의 마찰
지금 환경에서 몇 번 더 실제 프로젝트를 수행 된 뒤 프로젝트 추적 사이클이 잘 도는 것이 확인되면 제 메인 작업 컴퓨터인 맥북에도 도입할 생각입니다. 구조 전체를 복제하기보다 workspace-governance, lore-commits, project-lifecycle-management처럼 역할이 분명한 절차부터 옮기는 편이 좋을 것 같다고 생각합니다.
