이것은 16개 매체에 자동 배포하는 콘텐츠 기반 전체 아키텍처 심층 분석 시리즈 중 하나입니다. 지난번에는 「인덱스(Index) + 상세 파일로 나눈 영속 지식 계층」이라는 설계 사상을 작성했습니다. 이번에는 그 후속으로, 실제로 어떤 파일 형식으로, 어떤 판정 기준으로 운용하고 있는지를 추상화하지 않고 상세히 기술합니다.

지난 기사가 「생각하는 방식」이었다면, 이번에는 「구현」입니다.

상세 파일의 포맷: 4개 필드로 고정한다

상세 파일 1건은 반드시 다음 4개 필드를 가진 작은 텍스트 파일로 구성합니다.

---
name: {파일명과 대응하는 슬러그(Slug)}
description: {무엇에 관한 파일인가. 인덱스에 출력할 1줄 요약과 동일}
...

포인트는 description을 인덱스의 1줄과 파일 내부의 프론트매터(Frontmatter) 양쪽 모두에서 공유하는 것입니다. 인덱스 측에만 별도로 문장을 작성하면, 시간이 지남에 따라 「인덱스의 설명」과 「파일의 내용」이 어긋나게 됩니다. 한 곳을 수정하면 양쪽 모두에 반영되는 구조로 만듦으로써, 이러한 어긋남을 구조적으로 방지하고 있습니다.

4가지 분류, 각각의 본문 템플릿

지난번에 「지식을 성질에 따라 분류한다」고 썼지만, 분류마다 본문의 작성 방식 자체를 바꾸고 있는 것이 이번 구체화의 핵심 포인트입니다.

분류 1: 방침·피드백 — 「규칙 + 이유 + 적용 조건」의 3줄

{규칙 그 자체를 1줄로}
**이유**: {왜 그 규칙이 필요하게 되었는가. 대부분 과거의 실패나 사용자가 강력하게 정정한 경위}
**적용 장면**: {언제, 어떤 장면에서 이 규칙을 떠올려야 하는가}

여기서 가장 중요한 것은 이유를 반드시 쓰는 것입니다. 규칙만 적어두면, 나중에 비슷하지만 미묘하게 다른 상황에 직면했을 때 그 규칙을 적용해야 할지 판단할 수 없습니다. 「왜」까지 적어두면, 에지 케이스(Edge case)에서도 「이 이유에 부합하는가」를 통해 판단할 수 있습니다.

분류 2: 진행 중인 사실 — 「사실 + 이유 + 영향을 미치는 장면」

{현재 상황이 이러하다는 사실}
**이유**: {무엇이 그 상태를 일으키고 있는가. 마감일·제약 사항·스테이크홀더(Stakeholder)의 요청 등}
**적용 장면**: {이 사실을 바탕으로 어떻게 제안을 바꿔야 하는가}

방침·피드백과 템플릿은 비슷하지만, 성질이 다릅니다. 방침은 「에이전트(Agent)의 행동 방식」에 관한 영구적인 규칙이고, 진행 중인 사실은 「현재 프로젝트의 상태」에 관한 일시적인 정보입니다. 같은 3줄 구조라도, 이 사실은 부패한다(1~2개월이면 진부해진다)는 전제로 다룰 것인가가 분류상의 차이점이 됩니다.

분류 3: 참조처 — 포인터만 작성, 내용은 쓰지 않음

{어떤 정보가 어디에 있는가. 1~2줄}

이것은 의도적으로 얇게 작성합니다. 「상세 내용은 여기를 보라」는 포인터의 역할에 철저히 집중하여, 내용 그 자체를 이중 관리하지 않는 것이 목적입니다. 참조처의 실체(외부 시스템의 내용)는 계속 변하기 때문에, 여기에 상세 내용을 적어버리면 가장 먼저 진부해집니다.

분류 4: 영구적인 방식 — 「절차·트랩 + 발견 경위」

{습관·트랩·절차}
**발견 경위**: {어떤 실패/검증을 통해 이것을 알게 되었는가}

세 가지 중 가장 수명이 긴 분류입니다. 코드의 버그가 아니라 「환경이나 도구의 구조적인 특성(습관)」을 적기 때문에, 월 단위·년 단위로 유효합니다. 다만 「발견 경위」를 적어두지 않으면, 나중에 보았을 때 「정말로 아직 이 특성이 남아 있는가」를 검증하기 어려워집니다.

인덱스 (Index)의 1줄 포맷

- [{제목}]({파일 경로}) — {60~150자의 훅(Hook)}

이 훅은 **「왜 이것이 중요한가」가 아니라 「이것을 보는 순간 떠올려야 할 최단 경로의 단서」**를 작성합니다. 중요도에 대한 설명이 아니라, 검색성을 우선시한다는 뜻입니다.

인덱스에는 200행을 넘으면 오래된 엔트리(Entry)를 잘라낸다는 하드 제한을 두고 있습니다. 이유는 단순합니다. 인덱스 자체가 항상 컨텍스트(Context)에 포함된다는 전제이므로, 인덱스가 비대해지면 본말전도이기 때문입니다. 잘라내는 기준은 「최근에 참조되지 않음」, 「대응하는 프로젝트가 이미 종료됨」의 두 가지 포인트입니다.

쓰기 타이밍의 판정 플로우차트

지난번에 「쓰기는 사용자의 정정 시점과 예상치 못한 사실이 판명되었을 때로 상정한다」고 썼지만, 실제로는 한 단계 더 판정이 끼어 있습니다.

이 중에서 가장 효과가 컸던 것은 "Q1: 향후에도 재사용될 것인가"로 한 번 필터링하는 것이었습니다. 이를 도입하기 전에는 그 자리에서만 쓰이는 작업 메모까지 영속층 (Persistence Layer)에 기록해 버려서, 인덱스 (Index)가 금방 비대해지곤 했습니다. "이것이 반년 뒤의 다른 세션에서도 도움이 될 것인가"를 매번 자문하는 것만으로도 쓰기 (Write) 양이 크게 줄어들었고, 질이 향상되었습니다.

"시점의 스냅샷"을 지키는 구체적인 운용

지난번에 지식층 (Knowledge Layer)의 기술은 작성한 순간의 스냅샷 (Snapshot)에 불과하다고 썼습니다. 이를 철저히 하기 위해, 권장 사항을 포함한 상세 파일에는 "이것은 작성 시점의 상태임"이라는 전제를 명시하고, 행동에 옮기기 전에 실물 확인을 거치는 한 단계를 운용 규칙으로 정하고 있습니다.

구체적으로는, 상세 파일 내에서 "〇〇라는 파일/기능이 있다"라고 단정적으로 기술할 경우, 그것이 실제로 지금도 존재하는지 여부는 참조한 시점에 다시 한번 검증한다는 전제로 다룹니다. 파일 경로(File Path)나 함수명(Function Name)처럼 이름 변경이나 삭제로 인해 쉽게 정보가 어긋날 수 있는 항목일수록, 이 검증을 건너뛰고 싶은 유혹이 강해지지만, 그 단계를 건너뛰는 순간 영속층은 "오정보의 생산원"으로 전락하게 됩니다.

요약

지난번의 "인덱스 + 상세 파일"이라는 설계 사상을 실제로 운용 가능한 수준까지 구체화하면 다음 4가지로 집약됩니다.

• 상세 파일은 4개 필드 고정(슬러그/요약/분류/본문)하며, 요약은 인덱스와 공유하여 이중 관리를 피한다.
• 4가지 분류 각각에 전용 템플릿을 갖추어, "영구적 규칙"과 "일시적인 사실"을 작성 방식 단계에서 구분한다.
• 쓰기 전에 "재사용성 → 중복 체크 → 재도출 가능성"의 3단계 필터를 통과시킨다.
• 기술 내용은 항상 "시점의 스냅샷"이며, 행동 전 실물 확인을 운용 규칙으로 명문화한다.

추상적인 설계 사상은 재사용하기 쉬운 반면, 구현 단계까지 파고들지 않으면 "결국 어떻게 써야 하는가"에서 매번 길을 잃게 됩니다. 이번에 작성한 템플릿과 플로우차트 (Flowchart)는 그대로 다른 프로젝트에 이식할 수 있는 형태로 만들고자 했습니다.

Discussion