지금 실행하세요
대상: $ARGUMENTS
KB의 모든 문서는 컬렉션에 저장됩니다. 컬렉션은 kb/ 아래의 디렉토리로, 로컬 COLLECTION.md 파일을 가지고 있습니다 (예: kb/notes/, kb/reference/, kb/instructions/ 또는 설치된 라이브러리 컬렉션 kb/commonplace/notes/). 쓰기를 허용하는 각 컬렉션은 COLLECTION.md에 등록부, 품질 목표, 제공하는 타입, 링킹 규칙을 정의합니다.
프론트매터가 있는 문서는 경로 값을 가진 type: 필드를 포함하며, 이는 타입 스펙 문서를 가리킵니다 (예: type: kb/types/note.md 또는 type: kb/reference/types/adr.md). 프론트매터가 없는 파일은 암시적 text로 처리됩니다.
1단계 - 인수 분석
편집 모드: 첫 번째 인수는 기존 .md 파일의 경로입니다. 파일을 읽고, 경로에서 컬렉션을 추론하고, 프론트매터에서 type: 경로를 읽습니다. 프론트매터는 있지만 type:이 없는 경우, 편집을 시작하기 전에 해당 구조적 문제를 수정하세요. 프론트매터가 없으면 암시적 text로 처리합니다. 구조적 편집을 하기 전에 type:이 가리키는 타입 스펙 문서를 열어 확인하세요.
신규 작성 모드: 그 외의 모든 경우입니다. 인수에서 컬렉션, 타입, 주제를 추출합니다. 기본값: 컬렉션 notes, 타입 kb/types/note.md. 요청된 타입이 instruction이고 명시적 컬렉션이 없으면 컬렉션 instructions를 사용합니다.
신규 작성의 경우, 대상 컬렉션을 kb/ 아래의 로컬 COLLECTION.md가 있는 디렉토리로 확인합니다. 약식 이름 (예: notes)은 kb/notes/를 의미합니다. 해당 컬렉션의 ## Types 섹션을 읽고 나열된 타입 경로 중 하나를 선택합니다. 요청된 타입이 나열되지 않았고 사용자가 명시적 경로를 제공하지 않은 경우, 사용 가능한 타입을 나열하고 중단합니다. 사용자가 명시적 kb/.../*.md 타입 경로를 제공한 경우, 해당 파일을 열고 타입 스펙 문서인지 확인한 후 사용합니다.
2단계 - 컬렉션 규칙 로드
대상 컬렉션의 COLLECTION.md를 읽어 컬렉션의 작성 규칙(아웃바운드 링킹 규칙 포함)을 확인합니다. 아웃바운드 링킹 섹션(제목은 다양함 — 대상과 레이블을 명명하는 섹션을 찾으세요)을 찾아 이를 권위 있는 규칙으로 간주합니다. 이 섹션은 이 소스가 링크할 수 있는 대상 컬렉션, 제외된 대상, 각 소스-대상 쌍에 허용된 레이블, 각 레이블이 제공하는 독자 니즈를 알려줍니다. 내부 형식은 다양합니다 (대상별 블록, 대상 열이 있는 단일 레이블 테이블, 산문 형식) — 모양이 아닌 내용을 읽으세요. 참고할 별도의 링킹 문서는 없습니다.
대상 컬렉션에 COLLECTION.md가 없으면 하드 실패합니다. 쓰기를 허용하는 모든 컬렉션은 COLLECTION.md가 있어야 합니다. 등록부, 품질 목표, 링킹 규칙이 컬렉션을 구별짓는 요소입니다. 기본 규칙으로 진행하지 마세요.
3단계 - 타입 스펙 로드
선택한 타입 스펙 문서를 읽습니다. 해당 문서의 프론트매터에는 반드시 type: kb/types/type-spec.md, name, description, schema가 포함되어야 합니다. 본문은 아티팩트의 형태를 제공하며 템플릿 블록을 포함할 수 있습니다. 본문을 구조적 작성 계약으로 따르세요.
타입 경로가 없을 때 note로 폴백하지 마세요.
text의 경우, 사용자가 명시적으로 비구조적 캡처를 원할 때만 프론트매터 없이 원시 마크다운을 작성합니다. 그 외에는 kb/types/note.md를 사용하세요.
4단계 - 작성 전 검색
Write는 능동적 발견을 실행하지 않습니다 — 그것은 cp-skill-connect의 작업입니다. Write는 하나의 노트를 작성하고, 작성자가 이미 가지고 있는 링크와 저렴한 중복 방지만 커밋합니다:
- 근사 중복 확인.
rg를 사용하여 대상 컬렉션에서 새 노트의 고유한 제목 용어를 검색합니다 (예:rg -i "핵심 용어" kb/notes/ --glob "*.md"). 이는 대상이 지정된 용어 검색입니다 — 컬렉션 전체를 열거하지 마십시오. 전체 목록을 작성하는 것은 선형 컨텍스트를 소모하며 단일 노트의 중복 확인에 적합한 도구가 아닙니다. 근사 중복이 이미 존재하면, 두 번째 노트를 생성하는 대신 해당 노트를 편집하는 것이 좋습니다. - 이미 로드된 컨텍스트. 이번 작성을 위해 세션에 가져온 노트, 출처, 수집 자료는 일급 링크 후보입니다. 읽을 가치가 있었다면 링크를 고려할 가치가 있습니다.
- 사용자가 명명한 대상. 사용자가 프롬프트에서 언급한 링크 대상.
편집 모드에서는 대상 노트에 대한 역링크 조회도 실행합니다. 질의 1회, 본문 검색 없음 — 편집이 의존성을 고아로 만들지 않도록 합니다.
이 외의 모든 발견 — 컬렉션 전체 설명 스캔, 크로스-대상 탐사, 본문 검색, 태그 순회, 링크 추적, 역방향 엣지 추론 — 은 cp-skill-connect의 몫이며 여기에 속하지 않습니다. Write는 하나의 노트 작성에 집중합니다.
5단계 - 초안 작성 및 저장
타입 스펙 문서와 컬렉션 규칙을 따릅니다. 기존 파일을 편집하는 경우가 아니라면 # Title에서 소문자-하이픈으로 연결된 파일명을 생성합니다. 타입화된 아티팩트의 경우 type:을 타입 이름이 아닌 정확한 저장소-상대 경로의 타입 스펙 경로로 설정합니다.
특성(traits)은 명백히 정당화될 때만 설정합니다. 사용 가능한 특성과 그 의미는 대상 타입의 스펙에 정의되어 있습니다 (예: kb/types/note.md의 특성 테이블) — 기억된 목록이 아닌 거기서 어휘를 가져오세요.
편집 중에는 요청된 변경 사항이 필요하지 않는 한 기존 프론트매터와 링크를 유지합니다.
6단계 - 검증
작성 또는 편집한 노트를 검증합니다:
commonplace-validate path/to/file.md
중단하기 전에 구조적 실패를 수정합니다.
그런 다음 다음 단계로 cp-skill-connect를 제안합니다. 4단계는 작성자가 이미 가지고 있는 링크(로드된 컨텍스트, 사용자가 명명한 것)와 중복 방지만 커밋합니다. 그래프의 나머지 부분(컬렉션 전체 설명 스캔, 크로스-대상 후보, 본문 검색 결과, 태그 순회, 링크 추적, 역방향 엣지 후보)은 connect 스킬 아래에서만 드러납니다. 이 제안은 선택적인 다듬기가 아닙니다.
범용 메커니즘
다음 사항은 컬렉션에 관계없이 모든 타입화된 아티팩트에 적용됩니다.
프론트매터는 노트를 질의 가능하게 만듭니다. 프론트매터가 없으면 암시적 text입니다. 프론트매터가 있는 파일은 반드시 경로 값을 가진 type:을 포함해야 합니다. 대부분의 라이브러리 노트에는 description(큰따옴표로 묶인 50-200자)도 필요하며, 선택적으로 traits, tags, status를 포함할 수 있습니다.
**설명(Description)**은 요약이 아닌 검색 필터입니다. 테스트: 에이전트가 이 노트의 개념을 검색하여 5개의 결과를 얻었다면, 이 설명이 이 노트를 선택하는 데 도움이 될까요? 제목을 바꿔 말하는 것은 검색 가치를 전혀 더하지 않습니다.
어휘. 루트 AGENTS.md에 선언된 활성 어휘를 사용하세요. 산문을 작성하거나 실질적으로 편집할 때, 독자가 해당 용어를 모를 수 있는 첫 의미 있는 언급에서 활성 어휘를 설명하고 연결하세요. 어휘 링크만 추가하기 위해 건드리지 않은 구절을 변경하지 마십시오.
링크. 소스 파일을 기준으로 한 상대 마크다운 경로를 사용하세요. 모든 링크는 실제 파일을 가리켜야 합니다.
위치는 헌신 정도를 인코딩합니다. 인라인 산문 연결자(since [X](./x.md), because [X](./x.md), but [X](./x.md))는 가장 강력합니다 — 대상은 현재 논증의 전제입니다. 바닥글 링크는 명시적 레이블과 컨텍스트 구문을 전달합니다: - [제목](./경로.md) — 레이블: 컨텍스트 구문.
컬렉션의 COLLECTION.md는 대상별로 레이블을 승인하고 각 레이블이 제공하는 독자 니즈를 명명합니다. 링크의 목적과 일치하는 독자 니즈를 가진 레이블을 선택하세요. 컨텍스트 구문은 "[소스]가 [대상]에 연결되는 이유는 [구체적인 이유] 때문입니다"라는 질문에 답하도록 작성하세요. 승인된 레이블 중 적합한 것이 없으면, 해당 후보는 이 컬렉션의 범위를 벗어납니다 — 링크를 제거하거나 컬렉션 작성자에게 승인 확장을 요청하세요.
파일명은 소문자, 하이픈 연결, .md 확장자, # Title에서 유래, 최대 70자.
증류 추적: 노트에서 집중된 아티팩트로 증류할 때, 각 소스 노트의 바닥글에 Distilled into:를 추가하세요. 증류된 아티팩트는 다시 링크하지 않습니다.
이름 변경: 수동으로 이름을 변경하지 마세요. commonplace-relocate-note를 사용하여 역링크를 업데이트하세요.