20_Projects/전자책 발행/AI와 함께하는 Obsidian 제텔카스텐/AGENTS.md

AGENTS

전자책 집필 지침

이 폴더의 원고와 목차를 작업하기 전에 AI와 함께하는 Obsidian 제텔카스텐 프로젝트 개요의 집필 원칙과 다루지 않는 내용을 확인합니다.

• 책의 제목은 AI와 함께 만드는 Obsidian 제텔카스텐입니다.
• 부제는 Copilot으로 기록하고, 연결하고, 발행하는 자유로운 지식관리입니다.
• 이 프로젝트에는 두 개의 동등한 산출물이 있습니다: 독자가 읽는 전자책과 다음 책에도 재사용할 AI 전자책 집필 시스템입니다.
• 집필 중 반복 가능한 선호·판단·실패를 발견하면 현재 원고만 수정하지 말고 프로젝트 개요, AGENTS.md, 템플릿 또는 체크리스트에 남길지 검토합니다.
• 현재 책에만 필요한 내용과 다른 전자책에도 재사용할 범용 규칙을 구분합니다.
• 프로젝트 개요에는 판단의 이유를, AGENTS.md에는 반드시 지킬 실행 규칙을, 템플릿/에는 반복 형식을 기록합니다.
• 규칙을 미리 과도하게 만들지 않고 실제 원고에 적용해 검증된 뒤 재사용 자산으로 승격합니다.
• 집필 우선순위는 제목 → 들어가며 → 목차 → 마치며 → 실제 본문입니다.
• 본문을 확장하기 전에 앞의 네 요소가 같은 약속과 독자 변화를 가리키는지 확인합니다.
• 목차는 기능 목록이 아니라 기록 → 연결 → 안심하고 지속 → 완성·발행의 변화 경로로 구성합니다.
• 들어가며에서 만든 기대를 마치며의 즉시 행동으로 회수합니다.
• 이 책은 Obsidian 기초서가 아니라 AI를 활용한 실무 중심의 지식관리 실용서입니다.
• 최우선 목적은 독자에게 호기심·동기·자신감을 주고, 완독 직후 실제 행동을 시작하게 하는 것입니다.
• A부터 Z까지 빠짐없이 설명하는 것은 목적이 아니라 독자의 행동을 돕는 수단입니다.
• 정보의 양보다 독자가 “나도 할 수 있다”, “지금 바로 해 보고 싶다”고 느끼는지를 우선합니다.
• 초반에는 완성된 사용 경험과 효용을 보여 주고, 작은 성공을 빠르게 경험시킨 뒤 세부 기술을 소개합니다.
• 개념과 구조는 필요한 장에서 why와 함께 처음 소개하며, 뒤에서 사용할 예시를 앞 장의 선행 조건으로 만들지 않습니다.
• 1장의 첫 실습에서는 기존 메모 하나만 요구하고 폴더 구조나 문서 생명주기를 요구하지 않습니다.
• 00_Inbox 등의 폴더 체계는 문서 생명주기 장에서 저자의 실용적인 제안과 철학으로 소개합니다.
• 각 장은 독자가 즉시 실행할 한 가지 행동과 확인할 수 있는 결과로 끝냅니다.
• 지금 할 한 가지의 도입문은 행동 하나를 단일 동사로 선언한다(…적습니다, …켜고 …시켜 봅니다). 절차 단계는 numbered list로 둔다.
• 잘되지 않을 때 확인할 것의 소제목은 독자가 호소하는 증상형으로 쓴다. 주어가 필요하면 명시한다(예: ### AI가 규칙을 잘 따르지 않습니다).
• 육하원칙 중 why와 what을 최우선으로 설명하고, 이를 이해시킨 뒤 when·how·who·where를 다룹니다.
• 독자가 IT 전문용어를 모를 수 있다고 전제하고, 가능한 한 쉬운 한국어를 먼저 사용합니다.
• 피할 수 없는 전문용어는 책 전체에서 처음 등장하는 장에서만 각주를 붙이고 해당 장 하단에서 1~3문장으로 설명합니다.
• Copilot, vault, frontmatter, wikilink, CLI, BYOK처럼 혼동 가능성이 높은 용어를 우선 설명하고, 이미 앞 장에서 정의한 용어에는 각주를 반복하지 않습니다. 반복 설명이 필요하면 부록 용어집에서 모읍니다.
• 이 책의 Copilot은 Microsoft Copilot이나 GitHub Copilot이 아니라 Copilot for Obsidian임을 첫 등장 각주에서 밝힙니다.
• 본문에 코드·식별자를 처음 쓸 때는 한국어 명칭을 앞에 둔다. 예: 공개 여부(is_public). 코드 식별자가 주어 자리에 먼저 나오지 않게 한다.
• 각 장은 기본적으로 왜 필요한가 → 무엇을 얻게 되는가 → 어떻게 적용하는가 → 지금 할 한 가지 순서로 구성합니다.
• 각 장에 핵심 callout을 1개 둡니다(최대 2개). 반드시 알아야 하는 원칙은 [!important], 꼭 해야 하는 행동은 [!tip]으로 씁니다.
• callout은 2~3문장으로 짧게 쓰고, 관련 섹션 바로 뒤에 배치합니다.
• AGENTS.md 예시나 요청문을 본문에서 다시 말할 때는 원문을 그대로 인용한다. 풀어쓰면 둘을 대조하는 독자가 어긋남을 느낀다.
• 절차와 기능을 설명하기 전에 독자의 문제, 목적, 기대 결과가 분명한지 확인합니다.
• 이미지가 유용한 위치에는 AI 이미지 자리 템플릿 형식의 숨은 IMAGE_PLACEHOLDER 주석을 넣습니다.
• 원고를 처음 작성하거나 수정할 때는 실제 이미지를 생성하지 않고 prompt-ready placeholder만 작성합니다.
• 실제 이미지 생성과 삽입은 원고 구조가 안정된 뒤 별도 배치 작업으로 한꺼번에 진행합니다. 사용자가 개별 생성을 명시한 경우는 예외입니다.
• 이미지 수를 기계적으로 채우지 말고 서사의 전환, 개념 이해 또는 화면 확인에 실제로 기여하는 위치만 선택합니다.
• 이미지 자리와 제작 정보는 독자에게 노출하지 않으며, 최종 원고에는 실제 이미지와 필요한 caption만 표시합니다.
• UI와 절차는 스크린샷을, 감정·비유·생활 장면은 AI 이미지를 우선 고려합니다.
• 모든 이미지에는 목적, 고유 ID, title, alt, 비율, 저장 경로와 제작 상태를 기록합니다.
• 실제 이미지를 넣은 뒤에도 prompt와 제작 메타데이터는 주석으로 보존합니다.
• 독자가 Obsidian의 기본 조작과 Markdown 작성법을 안다고 전제합니다.
• Obsidian의 정의와 설치법, 제텔카스텐·PARA의 역사와 기초 개념은 별도 장으로 다루지 않습니다.
• Obsidian CLI는 부록에만 두지 않고 기본 작업 흐름에서 사용합니다.
• AI가 검색·backlinks·unresolved links를 확인하거나 노트를 rename·move할 때는 가능한 경우 실행 중인 Obsidian의 공식 CLI를 사용합니다.
• 이 작업 환경에서는 sandbox 안의 CLI가 실행 중인 호스트 Obsidian을 찾지 못할 수 있습니다. The CLI is unable to find Obsidian만으로 Obsidian이 꺼졌다고 판단하지 않습니다.
• 링크 인식 rename·move처럼 CLI가 필요한 작업은 허용 범위에서 승인된 외부 실행을 사용하고, CLI를 사용할 수 없을 때만 참조 링크를 전체 검색해 직접 갱신합니다.
• fallback을 사용한 경우 backlinks와 unresolved links를 Obsidian 인덱스로 검증하지 못했다는 점과 대신 수행한 검색 검증을 구분해 보고합니다.
• CLI는 독자의 이득을 먼저 설명하고, 명령어 목록은 본문을 방해하지 않도록 필요한 만큼만 제시합니다.
• 개념 설명은 실습에 필요한 만큼만 제공하고, 실제 문제·작업 흐름·명령·예시·결과물을 중심으로 씁니다.
• 메커니즘을 처음 설명할 때는 주체·대상·조건을 한 문장에 완결한다. 앞에서 가르치지 않은 지식을 전제로만 쓰지 않는다.
• 기능을 나열하거나 특정 방법론을 정답처럼 가르치지 않습니다.
• 모든 기능은 독자가 얻게 될 편리함·편안함·자유·안심·경제성·확장성과 연결해 설명합니다.
• 일상의 구체적인 사용 장면을 통해 기록이 쌓이고 연결되며 성장하는 즐거움이 느껴지게 씁니다.
• 현재 구현해 사용 중인 흐름과 앞으로 구현할 계획은 명확하게 구분합니다.
• 비용은 ‘무료로 시작하고 필요할 때만 확장한다’는 관점으로 설명합니다.
• 기존 Claude·ChatGPT 구독, API 키와 로컬 모델을 재사용할 수 있다는 점을 포함합니다.
• 무료 모델과 요금제는 변동될 수 있으므로 출간 전에 공식 자료로 다시 검증하고, 한도와 개인정보 조건을 함께 씁니다.
• 문체는 독자에게 말하는 자연스러운 존댓말로 통일합니다. 다만 callout이 독자의 자기 다짐·셀프 안내인 경우 평서형으로 쓸 수 있다.
• ‘두 가지’, ’세 가지’처럼 숫자를 명시한 병렬 열거는 numbered list로 정리합니다. 각 항목은 한 문장의 존댓말로 끝내는 것을 기본으로 하고, 숫자 바로 뒤에 나오는 “그 세 가지는…” 따위의 총괄 재진술은 중복이므로 넣지 않습니다. 표가 이미 나열하는 내용(역할 분담 표 등)은 리스트로 중복하지 않습니다.
• 맞춤법은 조사(에/에서, 을/이 혼동)와 주어-서술어의 태(능동/피동 충돌)가 어긋나지 않게 씁니다. 띄어쓰기와 외래어 표기는 프로젝트 전체에서 일관되게 합니다.
• 원고 검토 시 각 문단의 핵심 주장을 한 줄씩 추출해 문단 간 중복을 전수 확인합니다. callout은 본문 문장을 통째로 복사하지 않고 각도를 달리해 요약·강조합니다.
• 문단 안에서 주장·원인이 둘 이상 섞이지 않는지 확인합니다(요약 한 문장 검증 — 둘이면 병렬인지 체인인지 구분). 부정 표현(“문제는 X가 아니라 Y”)은 독자가 실제로 가질 법한 오해와 짝을 맞춥니다. 나열형 부정(“A도 B도 아니다”)은 항목마다 짝이 있는지 확인해, 앞 문단이 만들지 않은 오해를 겨냥하는 항목은 뺍니다. 관념어(좋은 생각, 엉성한 모습)는 구체 장면으로 대체합니다.
• 문장을 검토할 때는 형식(지침 규칙 준수)과 내용(하려는 말을 하는지)을 둘 다 확인합니다. 형식이 맞아도 하려는 말과 어긋나면 고칩니다. 각 문장이 하려는 주장을 한 줄로 재구성한 뒤, 조사와 어미(특히 양보 -라도/-어도, 인과 -어서/-니까, 조건 -면)가 그 주장에 복무하는지 봅니다.
• 섹션을 검토할 때는 문장을 보기 전에 그 섹션이 하려는 일을 한 줄로 먼저 적는다. 틀이 어긋나면 문장 손질보다 틀 수정을 먼저 제안한다.
• 문단을 이어 읽으며 다음 문단이 왜 나오는지(전이 문장) 확인합니다. 특정 문단이 왜 뒤에 오는지 설명이 없으면 단절로 보고, 앞 문단이 만들지 않은 오해를 겨냥하는 부정이 없는지 함께 봅니다.
• 원고를 검토할 때는 저자의 눈이 아니라 타겟 독자(Obsidian 입문자·AI 미활용자) 의 눈으로 봅니다. 문제 장면·예시가 타겟 독자가 실제로 할 행동인지, 지시가 바로 실행 가능한지(어디로 가면 되는지), 오해할 지점이 없는지, 사용자는 같은 매뉴얼체 대신 독자에게 말하는 어투인지를 확인합니다.
• 각 장의 전개 리듬을 문제 장면 → 핵심 한 문장 → 구체 예시 → 복사 가능한 것 → 지금 할 한 가지로 통일합니다.
• 문제 장면은 독자의 하루에서 가져온 짧은 상황 1개 이상으로 시작합니다.
• 구체 예시는 실제 요청문·대화·메모 중 1개 이상을 전문에 가깝게 보여 줍니다.
• 대화 예시에서 독자 발화자의 말머리는 사용자:로 쓴다. 서술 어투의 ’여러분’과 구분한다.
• 복사 가능한 것(요청문, 규칙, 명령)을 각 장에 1개 이상 포함합니다.
• 본문 분량은 2,500~5,000자를 기준으로 합니다. 숫자를 채우기 위한 부풀림을 금지하고, 장의 전개 리듬(문제 장면 → 핵심 한 문장 → 구체 예시 → 복사 가능한 것 → 지금 할 한 가지)이 갖춰졌는지로 충분함을 판단합니다. 명제 나열만으로 짧게 끝내지도, 같은 설명의 반복으로 길게 늘리지도 않습니다. 마치며는 들어가며의 기대를 즉시 행동으로 회수하는 글이라 분량 기준 미달을 허용합니다.
• 원고마다 실제로 따라 하거나 복사해 적용할 수 있는 내용을 포함합니다.
• 새로운 장을 제안하거나 목차를 변경할 때도 위 원칙을 우선합니다.