[AX 사내도입까지? 시즌 2-01] Dorito's AI Agent Memory System (진행 중)

아무튼 초안 작성 완료! 보일러플레이트는 깃허브에 업로드는 해두었는데, 조금 더 완성도를 높인 이후 레포 링크 공유하겠습니다.

// TODO: 가독성 개선 + 직역어투 제거 + humanize 진행할 예정 + em—dash 제거할 거임 (2026-06-24 기준)

 

들어가며

시즌 1 "AI 메모리 시스템 적용기"에서는 살짝 얼기설기 아쉬운 점이 많았죠? 

그래도 동작은 잘 되더군요. 자, 시스템을 완성했다면, 이제부터는 그 설계가 어떻게 제가 개선해나갔는지를 정리해볼 예정입니다.

저는 이 구조를 실제 프로젝트에 3개월간 운영했습니다.

먼저 이 글을 읽고 구조를 이해한 후, 회고 시리즈에서 "왜 이게 필요했나"를 보시면 더 명확합니다. (- 이 구조가 정말 작동했는지 - 어떤 부분을 더 개선했는지 - 도구를 바꾸면서 뭘 조심했는지 등등..)

정말 솔직하게 말하자면, 시즌 1 "AI 메모리 시스템 적용기" 는 글을 작성하면서 시스템을 만들던 상태였기도 하고, 모르는 부분도 많았어서 글을 쓰면서 배우는 점도 많았습니다. 그래서 제가 봐도 글이 너무 장황하고, 너무 verbose 해서 품질이 매우 낮은 회고록에 가깝습니다. 솔직히 부끄럽기도 해요. 글 자체가 AI 티가 많이 나고...... 등등 이하 생략할게요.  (i-am-not-ai humanize strict 으로 돌렸는데도 특유의 AI 문체는 해결하기 어렵더라구요. 결국은 수제 타이핑이 필요합니다. ㅠㅠ) 

 

여기 도착하기까지 더 멋지고, 최적화 및 더 기능이 눈부시게 발전된 AI 에이전트 컨텍스트 메모리 하네싱 시스템을 구축 완료했어요.

이에 시즌 2를 연재해보려고 합니다. 팀원분들도 다들 llm wiki 에 고민을 많이 하고 계셔서 제 시스템에 대해서 정말 많은 관심을 주셨습니다. 심지어 이번에는 회사에서 AX 담당자 역할을 해달라는 요청까지 들어왔습니다.!! 

 

그리고 AX 담당자로서 설득한 포인트들까지 의사결정 관련도 많이 회고해볼 것 같습니다. 

 

왜 이런 구조가 나왔는지, 어떤 삽질들을 해서 이 시스템까지 도달하게 되었는지 우여곡절에 대해서는 다음 편에서 기대해주세요! 

• 결정의 진실 출처를 한 곳으로 통일하면서 의사결정 문서 시스템을 더 좋게 고도화하였습니다. (SSOT)
• AI Agent 벤더 락인 문제 해결: Claude 에만 의존하는 시스템이었는데, thin router 를 통해서 자유롭게 AI agent 를 선택할 수 있게 되었습니다. (codex, cursor, windsurf 기준으로 했고 Gemini 는 26년 6월 기준 서비스 종료라고 해서 제거 했습니다.
• 진행 중인 작업과 닫힌 결정을 명확히 분리해야 했습니다. 파일 기반 실행 상태 관리로 전환하고 llm wiki 의 컨텍스트를 손상시키지 않도록 개선하였습니다. (GSD + wiki)  
• 자동화의 책임을 명확히 해야 했습니다 (AI가 할 것 vs 사람이 할 것).
• 사람이 꼼꼼히 읽지 않고 대충 넘어가는 걸 막으려고 Review Gate Quiz를 추가했습니다. (매우 흥미로우실 거에요.)
• 레거시 문서들에 대해서 폐기된 규칙과 옛 아키텍처를 보존하고, 점진적으로 삭제 처리 완료했습니다.

---

이 글은 "시스템 최종 정리본"입니다. 

 

한 줄 요약 — AI 코딩 에이전트에게 매번 같은 설명을 반복하는 대신, 프로젝트의 규칙·진행 상태·결정 기록을 코드 저장소 안의 문서로 나눠 둡니다. 그러면 대화 세션이 끝나도, 쓰는 도구가 바뀌어도, 담당자가 바뀌어도 같은 맥락에서 이어집니다.

 

사람은 새 프로젝트에 들어올 때 안내 문서, 개발 규칙, 설계 문서, 작업 히스토리를 먼저 봅니다. AI 에이전트도 작업 전에 같은 기준 문서를 읽게 만들면, 사람이 매번 대화로 전체 맥락을 다시 설명하지 않아도 됩니다. 이 문서는 그 체계를 도입할지 검토하는 분들을 위한 안내서입니다. (용어가 처음 나올 때는 괄호로 쉬운 풀이를 답니다.)

지금까지                          도입 후
─────────────────────────         ─────────────────────────
대화로 매번 설명                   저장소 안 기준 문서를 참조
세션이 끝나면 맥락 소실            세션·도구·담당자가 바뀌어도 맥락 유지
도구가 바뀌면 작업 기준이 흔들림   진행 상태와 장기 지식을 분리해 보존
긴 대화에서 초반 결정이 누락       결정은 별도 기록으로 추적 가능

읽는 순서: 1~2장은 왜 필요한지(문제·효과), 3~5장은 어떻게 생겼는지(예시·구조), 6~7장은 어떻게 운영하는지(도구별 차이·원칙·환경)입니다.

---

1. 문제 정의

지금의 AI 코딩 도구는 한 번의 대화만으로는 다음을 세션 사이에 안정적으로 유지하기 어렵습니다.

• 프로젝트 구조와 폴더별 역할
• 코드 작성 규칙과 하지 말아야 할 것
• 기존 의사결정의 맥락("왜 이렇게 했는가")
• 진행 중인 작업이 어디까지 왔는지

반복되는 문제는 셋으로 정리됩니다.

문제	무슨 일이 벌어지나
맥락 초기화	폴더 역할, 코드 규칙, 과거 결정의 이유, 작업 진행 상태를 새 대화마다 처음부터 다시 설명해야 합니다.
문맥 압축	AI가 한 번에 기억할 수 있는 양(문맥, context)이 차오르면, 앞에서 정한 근거와 제약이 요약·생략되어 결정이 흔들립니다.
도구 표류	AI 작업 도구마다 설정과 통제 방식이 달라, 같은 작업 흐름이 도구를 옮기면 끊깁니다.

핵심 전제 — AI가 코드를 못 짜는 것이 핵심 문제가 아닙니다. 진짜 문제는 "왜 이렇게 만들었는지, 무엇을 건드리면 안 되는지, 어떤 결정이 어떤 맥락에서 나왔는지"를 세션 사이에 안정적으로 보존하지 못한다는 점입니다. 한 사람이 오래 쌓은 맥락이 다음 세션으로 넘어가지 못하면, 작업 품질은 그때그때 운에 좌우됩니다.

해결 방향은 단순합니다. 사라지는 대화 대신 저장소 안의 파일을 기준으로 삼습니다. AI가 작업 전에 참조할 기준 문서를 저장소에 두고, 진행 상태와 닫힌 결정도 파일로 남깁니다. 그러면 다음 세션이 같은 파일을 읽고 이어받습니다.

---

2. 기대 효과와 비용

작업할 때

효과	내용
반복 설명 감소	구조·폴더 역할·코드 규칙을 매번 다시 적지 않고, AI가 기준 문서를 먼저 읽습니다.
작업 품질 안정화	같은 요청에 대한 결과 편차가 줄어듭니다. 매번 같은 규칙·맥락을 기준으로 작업합니다.
기존 구조 훼손 감소	폴더 역할·규칙이 문서로 있어, 수정이 기존 구조를 깨는 경우가 줄어듭니다.
이어받기	진행 상태·결정 이유가 파일에 남아 다음 세션·다른 도구·다른 담당자가 같은 지점에서 이어받습니다.

팀 단위

효과	내용
AI 활용 표준화	사람마다 다른 대화 습관에 기대지 않고 같은 기준 문서를 공유합니다.
의사결정 추적	닫힌 결정·기각한 선택지·번복 조건을 나중에 추적합니다.
합치기 전 자동 점검	문서 링크·표기 규칙 등을 코드 합치기 전에 자동으로 검사합니다.
온보딩 재사용	AI용 기준 문서를 사람 온보딩 문서로도 사용합니다.

비용 (트레이드오프)

효과만 보면 판단이 한쪽으로 기웁니다. 비용도 함께 봅니다. 이 방식은 만능 해법이 아닙니다.

항목	설명	완화 기준
문서 유지 비용	무엇을 남기고 무엇을 버릴지 판단해야 합니다.	작은 수정까지 전부 기록하지 않고, 비용·재질문·의존성 기준으로 선별합니다.
사람의 최종 확인	무엇을 기록하고 오래 보관할지는 AI가 1차로 판단합니다. 사람은 정확성을 다시 확인하고 공식 문서로 옮겨도 되는지 최종 승인합니다.	AI는 제안자, 사람은 승인자로 역할을 나눕니다.
도구 의존성	자동 통제의 강도는 도구마다 다릅니다. 현재는 특정 도구에서 가장 강하게 동작합니다.	도구가 바뀌어도 기준 문서 계층은 그대로 유지되도록 설계합니다.

---

3. 워크플로우 예시

실제로 진행한 한 건을 일반화해 보여 드립니다. 요청은 한 줄이었습니다.

"화면의 에러·로딩 처리가 들쭉날쭉하다, 한번 봐줘"

이 한 줄이 분류 → 조사 → 영향 분석 → 검토 → 반영까지 가는 동안, 기준 문서와 진행 상태 파일이 어떻게 쓰였는지 봅니다.

단계	한 일
요청 분류	"에러 처리 봐 달라"는 결정을 닫는 일보다 조사에 가깝습니다. 장기 지식이 아니라 진행 상태로 잡습니다.
조사	별도 문맥의 읽기 전용 보조 에이전트가 코드를 살펴보고 결과만 보고합니다. 메인 대화의 문맥이 조사 원문으로 덮이지 않습니다.
영향 분석	바꿀 부분을 코드 구조 지도(코드의 연결 관계를 보여 주는 보조 도구)에 물어, 영향받는 범위만 확인합니다. 전체를 다시 읽지 않습니다.
검토	변경된 내용을 검토용 에이전트가 살펴보고 통과/보류를 판정합니다.
반영	팀 규칙대로 작업용 가지(branch)에서 통합용 가지로 올립니다.

무엇을 고치고 무엇을 남겼나. 조사가 끝났다고 바로 결정 문서를 쓰지 않습니다. 에러 표시 방식("무엇을 어디에 보여줄지")은 아직 안 정해져서 결정 기록 조건을 못 채웁니다. 그래서 이번 반영에는 답이 분명한 수정만 담았습니다(예: 검색이 실패해도 멈추지 않고 계속 돌던 로딩 표시를 멈추도록 고치고, 화면 낭독 보조 기능을 위한 표시 추가). 표시 방식 같은 열린 질문은 논의로 남겨 두었습니다.

버그를 고친 것보다 중요한 것은 이어받기입니다. 답이 분명한 것만 반영하고 열린 질문은 논의로 남겨 두면, 같은 문제가 다음 세션·다른 도구·다른 담당자에게 넘어가도 진행 상태와 근거가 제자리에 남아 이어받을 수 있습니다.

---

4. 전체 구조

세 개의 폴더(레이어)를 구분하면 나머지는 따라옵니다. AI 도구는 작업을 시작할 때 라우터(시작 안내 파일) 를 먼저 읽고 각 폴더로 들어갑니다.

그림 1. 작업 도구 → 시작 안내 → 세 레이어

 

레이어	역할	담는 것	안 담는 것
세션 운영	지금 어떻게 행동할지	행동 규칙, 제품·팀·기술 요약본, 반복 선호, 반복 절차	결정 원문, 긴 진행 상태, 회의록
진행 상태	작업이 어디까지 왔는지	진행 중 계획, 작은 후속 작업, 열린 논의, 확신 낮은 아이디어	닫힌 결정의 최종 기준, 반복 운영 규칙
장기 지식	다음 달에도 믿을 기준	닫힌 결정, 운영 가이드, 회고	진행 중 계획, 열린 질문

쉽게 말하면 — 세 폴더는 각각 "지금 어떻게 행동할지", "작업이 어디까지 왔는지", "다음 달에도 믿을 기준"을 맡습니다. 진행 중인 상태와 오래 갈 지식을 한 곳에 섞지 않는 것이 핵심입니다.

보조로 코드 구조 지도 가 있습니다. 이것은 문서 검색기가 아니라, 코드의 구성 요소가 어디서 어떻게 연결되는지를 보여 주는 지도입니다. "이 부분이 어디서 쓰이나"는 여기서 보고, "왜 이 방식을 택했나"는 장기 지식 폴더에서 봅니다.

---

5. 세션 운영 폴더 — 행동 규칙과 자동 장치의 책임 경계

세션 운영 폴더는 AI가 지금 세션에서 어떻게 행동해야 하는지를 정해 둔 곳입니다. 작업을 시작할 때 가장 먼저 참조합니다. 보통 세 가지 역할 파일로 나눕니다.

역할 파일	담는 것	넣지 않는 것
행동 규칙 파일	행동 규칙, 진행 방식, 용어 사전, "모르면 추측하지 말고 사람에게 물어보라"는 규칙	—
요약 컨텍스트 파일	제품·팀·주요 결정의 짧은 요약본(빠른 온보딩용)	원본 문서나 데이터 구조의 자동 복사본
메모리 파일	반복되는 선호와 작업 메모	제품 정책·데이터 구조·설계 결정

자동 장치(hook)의 책임 경계

자동 장치(hook, 훅) 는 세션이 시작되거나 도구가 무언가를 실행하기 직전·직후에 자동으로 도는 보조 프로그램입니다. 여기서 중요한 운영 규칙이 하나 나옵니다.

세션 시작 시 자동으로 AI에게 넣어 주는 것은 요약 컨텍스트 파일 하나뿐입니다. 행동 규칙 파일과 메모리 파일은 자동으로 밀어 넣지 않고, AI가 시작 안내 파일을 거쳐 직접 읽습니다. 이 셋이 모두 같은 방식으로 자동 주입된다고 가정하면 설정을 틀리게 됩니다.

운영 원칙 — 하나의 자동 장치는 하나의 책임만. 세션 시작 자동 장치의 출력이 너무 커지면, 그 안에 있던 사람 확인 요청 신호가 다른 출력에 묻혀 무시될 수 있습니다. 그래서 컨텍스트를 넣어 주는 장치는 요약 컨텍스트만 출력하고, 행동 규칙과 메모리는 별도 읽기 경로로 분리합니다.

왜 "파일 가져오기"가 아니라 "실행되는 주입 장치"인가

그림 2. 세션 운영 — 자동 장치의 책임 경계

여기에는 의도된 설계가 있습니다. 시작 안내 파일에 "이 파일 내용을 그대로 가져와라"는 정적 포함(고정된 파일 한 개를 통째로 붙이는 방식) 한 줄을 넣을 수도 있습니다. 하지만 이 체계는 일부러 그 방식을 피하고, 시작 시점에 실행되는 자동 장치(주입 장치)가 컨텍스트와 신호를 만들어 넣습니다. 이유는 셋입니다.

첫째, 상태에 따라서만 나오는 조건부 신호입니다. 사람 확인 요청 신호는 고정 문구가 아니라 그때그때의 환경 상태에 달린 정보입니다. 예를 들어 "이 컴퓨터에 초기 설정이 아직 안 됐다" 같은 상태는 지금 점검해야만 알 수 있습니다. 정적 포함은 고정 텍스트만 붙일 수 있어서, 이미 설정이 끝난 환경에서도 매번 같은 질문을 띄우는 불필요한 잡음이 됩니다. 게다가 설정 상태는 팀 공통이 아니라 사람·컴퓨터마다 다르므로, 저장소에 박아 둘 장기 지식이 아니라 실행 시점에 점검할 운영 신호로 다루는 것이 맞습니다.

둘째, "지식"이 아니라 "행동 지시"로 작동시키기 위해서입니다. 정적으로 포함된 내용은 AI에게 "참고할 지식"으로 인식되지만, 실행 장치가 주입한 신호는 "지금 수행해야 할 지시"로 작동합니다. 그 의미—단순 안내가 아니라 사람에게 확인받고 행동해야 한다는 점—는 행동 규칙 파일에 약속(컨벤션)으로 정의되어 있고, AI는 시작할 때 그 규칙을 먼저 읽어 이해합니다. 특히 AI 도구는 보통 사용자가 먼저 말을 걸기 전에는 스스로 발화하지 않는데, 이 신호를 첫 컨텍스트에 주입하면 사용자의 첫 메시지가 무엇이든 그 신호를 최우선으로 처리하게 만들 수 있습니다.

셋째, 신호의 가시성을 지키기 위해서입니다. 규칙·메모리 같은 큰 파일을 통째로 자동 주입하면 시작 시 출력이 비대해지고, 도구의 화면 출력 한계(약 32KB)를 넘으면 중요한 신호가 사용자 눈에서 잘려 나갈 수 있습니다. 그래서 큰 파일은 AI가 필요할 때 직접 읽게 하고, 핵심 운영 신호만 짧은 출력으로 유지해 사용자가 놓치지 않게 합니다.

---

6. 진행 상태 폴더 — 작업을 크기별로 나누기

진행 상태 폴더는 장기 지식 저장소가 아니라 현재 작업판입니다. 열린 논의, 실행이 확정된 작업, 큰 작업 흐름, 즉시 처리할 작은 수정을 서로 분리합니다.

칸	쓰는 때	안 넣는 것
바로 처리 / 작은 기록	아주 작은 수정, 즉시 처리 가능	논의가 필요한 설계 변경
할 일(확정)	실행이 확정된 단위 작업	아직 결론이 안 난 아이디어
논의	결론이 안 닫힌 토론·디버깅·질문 (결정 기록 전 단계)	공식 결정, 제품 정책
씨앗(아이디어)	확신이 낮은 가설·실험 아이디어	지금 실행할 확정 작업
큰 작업 흐름	여러 단계로 나눠야 하는 큰 작업	단발성 메모

작업 분류 흐름

자연어 요청이 들어오면, AI는 먼저 작업 크기와 확정도를 판단합니다.

그림 3. 자연어 요청의 작업 분류 흐름

 

 

엄격한 경계 — 진행 상태는 장기 지식을 대체하지 않습니다. 진행 중인 메모를 바로 장기 지식으로 올리지 않으며, 논의가 끝나 결론이 닫힌 뒤에만 옮깁니다. 제품 정책·데이터 구조·외부 약속·설계 결정은 진행 상태 폴더에 임시로만 두고 최종 출처로 삼지 않습니다.

---

7. 장기 지식 폴더 — 결정 기록과 상태표

장기 지식 폴더는 사람이 승인한 장기 지식입니다. 되돌리기 어려운 결정, 반복 운영 규칙, 사고와 교훈(회고)을 나눠 담습니다. 이 문서들은 다음 세션과 다른 도구가 다시 읽는 기준이므로 현재 사실과 맞아야 합니다.

결정 기록을 언제 쓰나

결정 기록(ADR, Architecture Decision Record — 왜 이렇게 정했는지 남기는 문서) 은 세 조건을 모두 충족할 때만 만듭니다.

1. 비용 — 되돌리는 비용이 큰가?
2. 재질문 — 나중에 "왜 이렇게 했지?"를 다시 물을 만한가?
3. 의존성 — 다른 작업이 이 결정에 의존하는가?

셋 중 하나라도 약하면 가벼운 메모나 변경 설명으로 충분합니다.

공식 문서로 옮기는 3단계 (마지막 승인은 반드시 사람)

역할 분담이 중요합니다. 무엇을 기록하고 오래 보관할지는 AI가 1차로 판단합니다. 사람이 하는 일은 그 판단을 대신하는 것이 아니라, 내용이 정확한지 다시 확인하고 공식 문서로 옮겨도 되는지 최종 결정하는 것입니다.

그림 4. 제안(AI) → 확인(사람) → 승인(사람)

 

중요 — AI 혼자서는 공식 기준 문서, 즉 단일 진실 출처(SSOT, 한 사실에 대해 믿을 출처를 하나로 둔다는 뜻) 를 확정하지 못합니다. AI는 제안하고 형식을 정리할 수 있지만, 정확성·충돌 여부·공식화의 최종 승인은 사람이 합니다.

문서 머리말 상태표

장기 지식 문서의 맨 위에는 작은 상태표(frontmatter, 문서 머리말 메타데이터) 가 붙습니다. 사람은 무엇이 최신인지(상태값)를 거르고, AI는 같은 표로 신뢰할 문서를 판단하고, 자동 점검 도구는 깨진 링크나 중복을 잡습니다. 담는 항목은 문서 종류, 작성·수정 일시와 담당자, 현재 상태(작성 중 · 활성 · 대체됨 · 폐기 등), 관련 문서 같은 것들입니다.

결정이 바뀌어도 원본을 지우지 않습니다. 상태값과 관계 표시로만 "대체됨"을 나타냅니다. 그래야 "왜 바뀌었나"의 추적이 남습니다.

합치기 전 점검 — 코드/문서를 합치기 전에 AI와 사람이 함께 짚습니다. 지금 쓰는 것이 진행 중 상태인지 닫힌 결론인지, 도구마다 다른 자동 통제 범위를 감안했는지, 기존 결정과 모순되는지. 결정이 바뀌거나 새로 생기면 사람에게도 객관식 질문을 던져 이해도를 확인합니다. 틀려도 점수만 매기고 작업을 되돌리지는 않습니다.

---

8. 도구별 시작 규칙과 통제 강도

AI 작업 도구들의 차이는 "어느 모델이 더 똑똑한가"보다 "어떤 파일을 자동으로 읽고, 어떤 자동 장치를 실행하고, 어떤 단계에서 막을 수 있는가"에서 나옵니다. 모든 도구는 시작 안내 파일에서 출발하며, 이 안내 파일은 짧게 유지하고 세부 규칙은 세션 운영 폴더로 넘깁니다.

도구 유형	자동 통제 강도	특징
자동 장치를 강하게 지원하는 도구	강함	시작·작업 직전·직후에 자동 장치가 돌고, 규칙 위반 파일 쓰기를 실제로 막습니다. 현재 가장 최적화.
부분 지원 도구	도구 설정에 의존	기준 문서는 읽지만 모든 차단이 보장되지는 않습니다.
규칙 파일만 지원하는 도구	설정에 의존	자동 장치 없이, 규칙 파일을 직접 읽게 합니다.
일반 AI 에이전트	자동 차단 없음/약함	"자동으로 된다"가 아니라 "어떤 파일을 읽고 어떤 명령으로 확인한다"로 운영합니다.

사람 확인 요청 신호 — 자동 장치 출력에 "사람에게 확인을 받아야 한다"는 신호가 붙으면, 그것은 단순 안내가 아니라 행동 지시입니다. AI는 그 내용을 사람에게 묻고, 승인받은 뒤에만 진행합니다. 자동 장치 출력을 흘려보내지 않습니다.

도구를 옮길 때는 시작 안내 파일이 올바른 기준 문서를 가리키는지, 폐기된 경로를 참조하지 않는지를 점검합니다. 이 점검은 "모든 도구가 같은 통제 강도를 가진다"가 아니라 "같은 시작 규칙을 가리킨다"는 뜻입니다.

---

9. 설계 하이라이트 — 단순한 프롬프트 모음이 아닌 이유

이 체계는 "AI에게 좋은 지시문을 모아 둔 것"이 아니라, 협업의 안정성과 비용 효율을 위해 다듬은 운영 설계입니다. 대표적인 다섯 가지입니다.

1) 컨텍스트 격리·최적화 (시작 토큰 약 58% 절감)

처음에는 세션을 시작할 때 운영 폴더 전체를 AI에게 강제로 다 읽혔습니다. 그랬더니 시작 출력이 비대해지고, 중요한 신호가 화면에서 잘리고, 매 세션 토큰이 낭비됐습니다. 그래서 정보의 성격에 따라 주입 방식을 나누도록 고쳤습니다.

• 자동 주입 vs 직접 읽기 — 제품 요약본만 시작 시 자동 주입하고, 방대한 행동 규칙과 과거 교훈은 AI가 필요할 때만 직접 읽게 했습니다. 그 결과 시작 컨텍스트 토큰이 약 58% 줄었고, 시작 출력을 도구의 화면 한계(약 32KB) 아래로 슬림화해 운영 신호의 가시성을 회복했습니다.
• 보조 에이전트 분리 — 방대한 코드 조사는 메인 대화를 더럽히지 않도록 별도의 읽기 전용 보조 에이전트에 맡기고 결과만 회수해, 메인 세션의 토큰 효율을 지킵니다.

2) 도구 독립 라우팅 (특정 도구 종속 방지)

특정 AI 도구에 묶이지 않도록 얇은 시작 안내 파일과 실제 지식을 분리했습니다. 각 도구의 진입 파일은 같은 핵심 운영 폴더를 가리키는 포인터 역할만 하고, 도구마다 다른 자동 장치나 명령 표기는 별도 어댑터에서 처리합니다. 핵심 규칙은 그대로 둔 채 작업 도구만 갈아탈 수 있습니다.

3) 지식의 유효 기간에 따른 3계층

정보가 머무는 위치를 "지금 할 일 / 이번 세션 규칙 / 영구 기준"으로 엄격히 나눠, 확정되지 않은 계획이 장기 지식과 섞여 '거짓 진실'이 되는 것을 막습니다. 진행 상태는 작업판일 뿐이고, 사람이 최종 승인한 결과물만 장기 지식에 남습니다.

4) 인간의 실수를 막는 2중 검증

AI가 문서를 대량으로 만들 때 생기는 "읽지 않고 승인" 문제를 시스템으로 막습니다.

• 검토 게이트 퀴즈 — 중요한 문서(결정 기록·가이드)를 고치면 AI가 사람에게 최대 3문항의 객관식 퀴즈를 내어 핵심 결정과 위험한 오해를 확인한 뒤에만 진행합니다.
• 저장 직전 강제 차단 — 이모지, 한국어 직역 슬랭, 민감 정보 등이 들어가면 AI가 파일을 저장하기 직전에 시스템이 막고 정정을 요구합니다.

5) 유지보수 자동화 (관리 부담 최소화)

사람이 일일이 챙기기 힘든 메타데이터 관리를 자동화에 맡깁니다. 커밋만 하면 문서의 수정 일시 갱신, 작성자 표기, 변경 이력 기록이 자동으로 이뤄지고, 정합성 점검(lint)이 깨진 링크·중복 식별자·폐기된 용어를 전수 검사해 지식의 선도를 유지합니다.

---

10. 운영하며 다듬어진 원칙

이 체계는 처음부터 완성된 것이 아니라 실제 운영과 회고를 거쳐 다듬어졌습니다. 거기서 도출한 일반 원칙입니다.

원칙	내용
기준점 먼저, 도구는 나중	구조와 기준점의 정의가 자리 잡기 전에 새 도구부터 얹으면, 기준이 낡은 채로 굳어 되돌리는 비용이 큽니다. 구조를 먼저 정한 뒤 도구를 붙입니다.
하나의 자동 장치는 하나의 책임만	자동 장치의 출력이 비대해지면 중요한 신호가 다른 출력에 묻힙니다. 장치마다 책임을 하나로 좁힙니다.
도구는 신중히 도입	자작·외부 도구를 검증 없이 들이면 매몰 비용과 "이미 만들었으니 쓰자"는 편향에 빠지기 쉽습니다. 효과는 같은 조건에서 비교해 판단하고, 효과가 없으면 과감히 걷어냅니다.
정합성은 자동 점검으로 강제	문서 링크·표기·상태표의 정합성은 사람의 주의력에 기대지 않고 자동 점검으로 합치기 전에 막습니다.

---

11. 도구 및 환경

옵시디언 /  문서 뷰어 (선택 사항) 

장기 지식 문서는 평범한 텍스트 형식이라 어떤 편집기로도 열립니다. 메모 앱(예: Obsidian) 같은 도구와 함께 쓰면 문서 머리말 상태표를 활용해 다음을 할 수 있습니다.

• 상태표 항목으로 문서 목록을 조건 검색(예: "현재 활성인 결정만 모아 보기")
• 의미가 비슷한 문서 자동 추천
• 새 문서 작성 시 상태표 자동 채우기

보조 스크립트 (개발자용, 자동 실행)

운영을 돕는 작은 자동 스크립트들이 있습니다. 비개발자가 직접 다룰 일은 없고, 대부분 자동으로 돌거나 합치기 전에 한 번 실행됩니다. 하는 일만 요약하면 이렇습니다.

• 초기 설정 점검 — 새 프로젝트에 이 체계를 들일 때 구성이 올바른지 확인합니다.
• 결정 목록 갱신 — 결정 기록 목록을 최신 상태로 맞춥니다.
• 문서 점검(lint) — 깨진 링크, 중복, 표기 규칙 위반 등을 합치기 전에 한 번에 점검합니다.

---