지식 베이스를 위한 AGENTS.md와 CLAUDE.md

AGENTS.md와 CLAUDE.md는 코딩 에이전트가 폴더에서 일하기 전에 읽는 일반 마크다운 파일이에요. 지식 베이스에서는 노트가 어떻게 짜여 있고 모든 문서가 어떤 규칙을 따라야 하는지 에이전트에게 알려 주는 곳이에요. 두 파일 모두 필수 필드나 스키마가 없어요. 일반 마크다운으로 지침을 쓰면 돼요.

이 가이드는 먼저 직접 구성하는 방법을 다뤄요. 부분마다 Knowtarium에서는 무엇이 달라지는지도 함께 보여 줘요. Knowtarium은 사람과 에이전트가 함께 쓰는, 저희가 만든 종단간 암호화 지식 베이스이고, 연결하는 모든 에이전트에게 규칙을 건네줘요.

AGENTS.md

AGENTS.md는 코딩 에이전트를 이끄는 열린 형식으로, Linux Foundation 산하의 Agentic AI Foundation이 관리해요. OpenAI Codex와 Cursor를 비롯한 많은 코딩 에이전트가 읽어요. 폴더 루트에 두고, 하위 폴더에 더 둘 수도 있어요. 편집하는 파일에서 가장 가까운 AGENTS.md가 우선하고, 채팅에 입력한 내용은 그 모두보다 우선해요.

CLAUDE.md

CLAUDE.md는 Claude Code 버전이에요. Anthropic 문서에 따르면 Claude Code는 여러 곳에서 이 파일을 읽는데, 범위가 넓은 것부터 읽어요.

조직은 관리형 CLAUDE.md를 배포할 수도 있어요. 파일끼리는 서로 덮어쓰지 않아요. Claude Code가 파일 시스템 루트부터 시작한 위치까지 차례로 이어 붙이니까, 가장 구체적인 지침이 마지막에 와요. 하위 폴더의 파일은 Claude가 그 하위 폴더의 파일을 읽을 때 불러와져요. CLAUDE.md는 @path/to/file로 다른 파일을 네 단계 깊이까지 불러올 수 있어요. Anthropic은 파일마다 200줄 안쪽을 권해요.

Knowtarium에서는

Knowtarium은 지침 파일로는 할 수 없는 확인 장치를 더해요. 에이전트가 내 규칙을 어떻게 다루든, 에이전트가 하는 모든 변경에는 서명이 남고 클릭 한 번으로 되돌릴 수 있으며, 그 권한을 줬을 때만 문서를 지우고, 어떤 것도 사람이 확인했다고 표시할 수 없어요. 검토를 켠 폴더에서는 에이전트의 변경이 내가 승인할 때까지 diff로 기다려요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

에이전트를 둘 이상 쓴다면 규칙은 AGENTS.md에 한 번만 쓰세요. 최근 버전의 Claude Code(v2.1.277 이상)는 폴더나 그 위에 CLAUDE.md나 CLAUDE.local.md가 없으면 알아서 AGENTS.md를 읽어요. Claude 전용 지침도 넣고 싶거나 이전 버전을 쓴다면, 옆에 그 파일을 불러오는 CLAUDE.md를 만드세요.

@AGENTS.md
 
## Claude Code
 
- 문서 세 개가 넘게 닿는 변경은 모두 plan 모드에서 작업해요.

Claude는 불러온 AGENTS.md를 먼저 읽고, 그다음 아래 줄들을 읽어요. 다른 에이전트는 모두 AGENTS.md를 직접 읽으니까, 규칙이 서로 어긋날 일이 없어요.

AGENTS.md 예시는 대부분 코드용이에요. 빌드 명령, 테스트, 스타일 같은 것들이요. 지식 베이스에는 다른 규칙이 필요해요. 아래는 에이전트가 노트를 많이 쓸 때 가장 중요한 규칙이에요.

폴더 구조

최상위 폴더마다 무엇을 위한 곳인지, 새 문서는 어디에 들어가는지 적으세요. 이게 없으면 에이전트가 폴더를 지어내고, 두 에이전트가 같은 종류의 노트를 서로 다른 곳에 둬요.

이름 짓기

파일 하나에 개념 하나, 이름 짓는 방식도 하나. 결정과 회의에 날짜가 붙은 이름을 쓰면 폴더가 저절로 정렬돼요.

링크

링크 방식을 하나 정하고 그렇다고 적으세요. 표준 마크다운 링크는 어떤 도구에서도 되지만, [[wikilinks]]는 일부에서만 돼요. 파일을 옮기면 링크도 고치라고, 그리고 아직 아무도 쓰지 않은 문서로 링크해도 된다고 에이전트에게 알려 주세요.

출처와 최신성을 위한 frontmatter

대부분의 템플릿이 빠뜨리는 규칙이자, 에이전트가 쓴 지식 베이스를 나중에 확인할 수 있게 해 주는 규칙이에요. 모든 문서가 누가 썼는지, 언제 낡는지 말하게 하세요. Google Cloud가 공개한 열린 명세인 Open Knowledge Format이 필드 이름을 정해 줘요. type(유일한 필수 필드), generated, verified, status, stale_after, sources예요. 공개된 형식을 쓰면 OKF를 읽는 어떤 도구든 내 노트를 이해해요.

출처 인용

모든 숫자, 날짜, 이름, 인용에 출처를 요구하고, 주장 바로 옆에 인용하게 하세요. 에이전트가 출처를 밝히게 하는 방법 가이드에서 더 깊이 다뤄요.

에이전트가 절대 하면 안 되는 것

넘으면 안 되는 선은 “절대” 규칙으로 쓰세요. 사람이 확인했다고 절대 표시하지 않기, 절대 지우지 않기, 사람의 편집을 절대 덮어쓰지 않기. Anthropic 문서에 따르면 구체적이고 간결한 지침이 일반적인 지침보다 더 일관되게 지켜져요.

확인을 기록하는 방법

에이전트가 문서를 확인했다면 정해진 방식으로 그렇다고 남겨야 해요. 시각이 붙은 자기 항목을 verified에 넣는 거예요. 그러면 누구든 에이전트의 확인과 사람의 확인을 구별할 수 있어요.

Knowtarium에서는

검토를 켠 폴더에서는 Knowtarium이 그 항목들을 신뢰 등급으로 바꿔요. 에이전트의 항목이 있으면 문서가 machine-confirmed, 내 항목이 있으면 human-reviewed가 되고, 마지막 변경 이후 둘 다 있으면 완전히 검증된 상태가 돼요. 거기서 에이전트의 변경을 승인하면 앱이 내 항목을 대신 써 줘요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

이 내용을 노트 폴더 루트의 AGENTS.md에 복사하고, 폴더 목록을 내 폴더에 맞게 바꾸세요. Anthropic이 권하는 200줄보다 넉넉하게 짧아요.

---
type: Instructions
title: 에이전트를 위한 규칙
---
 
# 지식 베이스: 에이전트를 위한 규칙
 
이 폴더는 사람과 에이전트가 함께 쓰는 지식 베이스예요.
모든 파일은 YAML frontmatter가 있는 일반 마크다운이에요(OKF v0.2).
무엇이든 바꾸기 전에 이 파일 전체를 읽어요.
 
## 구조
 
- 폴더마다 있는 index.md에 그 폴더에 무엇이 있는지 나와요. 먼저 읽어요.
- log.md에는 바뀐 내용이 최신순으로 기록돼요. 세션마다 한 줄을 추가해요.
- company/     미션, 용어집, 일하는 방식
- customers/   고객 세그먼트, interviews/ (인터뷰마다 파일 하나)
- metrics/     지표마다 파일 하나, 승인된 쿼리는 computations/에
- decisions/   결정마다 파일 하나, 이름은 YYYY-MM-DD-short-title.md
- references/  인용하는 원자료의 사본(PDF, CSV, 저장한 페이지)
- 최상위 폴더는 절대 새로 만들지 않아요. 먼저 물어봐요.
 
## 찾기
 
- 루트의 index.md에서 시작해서 링크를 따라가요. 모든 파일을 읽지 않아요.
- 쓰기 전에 검색해요. 그 주제의 문서가 있으면 그 문서를 고쳐요.
 
## 이름 짓기
 
- 파일 하나에 개념 하나. 파일 이름은 lowercase-with-hyphens.md 형식이에요.
- index.md와 log.md는 예약된 이름이에요. 문서 이름으로 절대 쓰지 않아요.
 
## 링크
 
- 표준 마크다운 링크를 쓰고, [[wikilinks]]는 절대 쓰지 않아요.
- 번들 루트 기준으로 링크해요: [Churn](/metrics/churn.md).
- 아직 없는 문서로 링크해도 괜찮아요. 링크를 고치려고
  빈 파일을 만들지 않아요.
- 파일 이름을 바꾸거나 옮기면, 그 파일로 가는 링크를 모두 고쳐요.
 
## Frontmatter
 
모든 문서는 frontmatter로 시작해요. 모르는 키는
있는 그대로 둬요.
 
```yaml
---
type: Metric                # 필수: Metric, Decision, Interview, ...
title: Churn
description: 한 문장, index.md와 검색에 쓰여요.
status: stable              # draft | stable | deprecated
generated: { by: <your-name>/<version>, at: <UTC time, ISO 8601> }
stale_after: <UTC time>     # 안심하고 인용할 수 없게 되는 시점
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: 결제 내보내기, 2026년 9월
---
```
 
- 쓰거나 바꾸는 모든 문서의 `generated`에 서명해요.
  의미 있는 변경마다 `generated.at`을 고쳐요.
- `stale_after`를 설정해요: 지표는 90일, 결정은 1년.
- 새 문서는 `status: draft`로 시작해요.
 
## 출처
 
- 모든 숫자, 날짜, 이름, 인용에는 출처가 있어야 해요.
- 짧고 바뀌지 않는 `id`로 출처를 `sources`에 추가하고, 주장 뒤에
  각주로 인용해요: 이탈률이 2.4%로 떨어졌어요.[^billing-export]
- 이번 세션에서 직접 연 출처만 인용해요. URL을 지어내지 않아요.
- 출처를 찾을 수 없으면, 사실처럼 쓰지 말고
  "## 미해결 질문" 아래에 적어요.
 
## 사람의 편집 확인하기
 
- 변경을 읽고, 그 문서로 링크하거나 같은 출처를 쓰는 문서를
  모두 읽어요.
- 모든 게 여전히 맞으면 `verified`에 자신을 추가해요:
  - { by: <your-name>/<version>, at: <UTC time> }
- 더는 맞지 않는 게 있으면 수정을 제안해요. 몰래 적용하지 않아요.
 
## 절대 하지 않는 것
 
- `verified`에 `human:` 항목을 절대 추가하지 않아요. 그건 사람만 해요.
- 다른 쪽의 `verified` 항목을 지우거나 순서를 바꾸지 않아요.
- 문서를 절대 지우지 않아요. `status: deprecated`로 설정하고 이유를 적어요.
- 사람의 편집을 절대 덮어쓰지 않아요. 동의하지 않으면 그렇다고 말하고 멈춰요.
- references/ 안의 파일은 절대 고치지 않아요. 그건 증거예요.
 
## 끝낼 때
 
- log.md에 날짜가 붙은 항목을 추가해요.
- 만들고, 바꾸고, 옮기고, deprecated로 바꾼 파일을 모두 나열해요.

Frontmatter 아래의 보관 기간은 내 기준으로 바꾸세요. OKF는 index.md와 log.md를 뺀 모든 .md 파일을 문서로 세기 때문에, 번들이 유효하도록 템플릿도 자기 frontmatter와 type으로 시작해요. 안에 든 frontmatter 예시 블록은 에이전트가 따라 쓰라고 넣어 둔 거예요.

어떤 규칙은 한 곳에서만 중요해요. AGENTS.md라면 metrics/AGENTS.md처럼 그 폴더에 파일을 하나 더 두세요. 에이전트는 가장 가까운 파일을 써요. Claude Code에는 경로 범위 규칙도 있어요. .claude/rules/ 안에 paths 필드가 있는 마크다운 파일을 두면, Claude가 맞는 파일을 읽을 때만 불러와져요.

---
paths:
  - "metrics/**/*.md"
---
 
# 지표
 
- 모든 지표는 metrics/computations/ 안의, 그 지표를 계산하는 쿼리로 링크해요.
- 새 출처 항목 없이는 숫자를 절대 바꾸지 않아요.

이렇게 하면 루트 파일이 짧게 유지돼요. Anthropic 문서는 지침 파일이 길수록 컨텍스트를 더 쓰고 덜 지켜진다고 경고해요.

Claude Code에서는 /context를 실행하고 Memory files 아래를 보면 파일이 불러와졌는지 확인할 수 있어요. 어떤 에이전트든 세션을 시작할 때 새 문서를 쓰는 규칙을 다시 말해 보라고 하세요. 말하지 못하면 파일을 읽지 않고 있거나 파일이 너무 긴 거예요.

그다음에는 약속이 아니라 결과를 확인하세요. 가장 흔한 실수는 grep 두 번으로 잡을 수 있어요.

# type이 없는 문서: OKF의 유일한 필수 필드
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# 슬그머니 끼어든 위키링크
$ grep -rn "\[\[" --include="*.md" .

같은 실수가 두 번 나오면 그에 대한 규칙을 추가하세요. CLAUDE.md에 대한 Anthropic의 조언도 같아요. 안 적어 두면 또 설명해야 할 것을 적어 두라는 거예요.

Knowtarium에는 규칙 스킬이 들어 있어서, 연결하는 모든 에이전트(Claude Code, Codex, Cursor, Claude Desktop 등)가 도구와 함께 받아요. 그래서 Knowtarium 지식 베이스의 규칙을 지침 파일마다 적어 둘 필요가 없어요.

스킬이 가르치는 것

• 워크스페이스의 인덱스부터 읽기. index.md가 있으면 그걸 읽고, 모든 문서를 불러오는 대신 그 링크를 따라가요.
• 쓰기 전에 읽기. 문서 전체보다 제목과 설명을 먼저 읽고, 모든 변경은 어떤 버전을 바탕으로 했는지 밝혀요. 그래서 에이전트는 읽지 않은 편집을 덮어쓸 수 없어요.
• 변경이 어떻게 반영되는지 알기. 대부분의 폴더에서는 변경이 바로 저장되고 되돌릴 수 있으니 신중하게 하고, 검토를 켠 폴더에서는 승인을 기다려요. 어느 쪽이든 사람에게 어느 쪽인지 알려요.
• 사람이 편집한 뒤 확인하기. 검토를 켠 폴더에서는 연결된 문서를 읽고, 모든 게 여전히 맞으면 확인 결과를 기록하고, 맞지 않으면 충돌을 표시해요.

내 AGENTS.md와 어떻게 나뉘는지

Knowtarium에서는 AGENTS.md가 곧 폴더의 지침이에요. 앱에서 쓰면, 에이전트가 거기서 노트를 쓸 때마다 함께 받아요.

어떤 규칙은 누가 파일을 읽느냐에 달려 있지 않아요. Knowtarium에서는 에이전트의 모든 변경이 그 에이전트의 키로 서명되고, 에이전트는 그 권한을 줬을 때만 문서를 지우고, 어떤 것도 사람이 확인했다고 표시할 수 없으며, 검토를 켠 폴더에서는 내 검토를 건너뛸 수 없어요. 에이전트는 연결된 워크스페이스와 폴더에만 닿아요. 앱 자체는 AI를 호출하지 않아요. 내 편집을 확인받고 싶을 때 에이전트에게 부탁하면, 에이전트가 스킬을 따라요.

에이전트는 npx knowtarium connect로, Claude Code와 Codex에서는 Knowtarium 플러그인(스킬이 들어 있어요)으로, Claude Desktop에서는 확장 프로그램으로, Cursor와 VS Code에서는 클릭 한 번으로 MCP에 연결해요. claude.ai나 ChatGPT 같은 채팅 앱용 커넥터는 나중에 나와요. 에이전트가 Knowtarium과 일하는 방식을 보세요.