Commonplace
하나의 시스템으로 작동하는 지식 시스템에 대한 연구(Research on knowledge systems, running as one).
Commonplace는 에이전트가 작동하는 지식 시스템을 위한 살아있는 교리이며, 실제로 구동하여 개발하고 테스트됩니다.
이것은 두 가지 목표를 가지고 있습니다. 실용적인 목표는 Andrej Karpathy가 스케치한 의미의 LLM 위키입니다. 이는 에이전트들이 사람들에 의해 지시되어 한 사람이나 프로젝트의 작업을 보존되고 연결된 노트로 전환하는, 지속적이고 링크된 Markdown 계층을 말합니다. 이론적인 목표는 새로운 학습 패러다임인 **이론 구축기(theory builder)**입니다. 이 시스템은 이론을 명제하고, 그 이론에 따라 행동하며, 이를 비판하고, 다음 라운드에 어떤 비판이 나타났는지 유지하는 방식으로 작동하며, 이는 칼 포퍼(Karl Popper)의 추측과 비판 방법론을 따릅니다. 우리는 오늘날의 LLM으로, 가중치(weights)를 고정시킨 상태에서 학습할 수 있는 완전 자동화된 이론 구축기가 만들어질 것이라고 믿습니다. 아직 이 가정에 대한 테스트는 실행되지 않았습니다.
이러한 목표들은 서로를 강화합니다. 왜냐하면 기억은 항상 학습에 관한 것이기 때문입니다: 노트는 시스템의 다음 행동을 변화시킬 때 가치가 있습니다. 행동하고, 비판받고, 수정되는 이론들이 위키가 학습하게 만드는 요소이며, 위키의 실제 사용은 문제점과 비판점을 제공하여 이론 구축기가 이를 학습하게 합니다.
성찰(Reflection)이 이 방법론의 핵심입니다. Commonplace가 노트를 작성하고, 연결하며, 수정하는 방식에 대한 교리는 그 자체가 비판하고 수정하는 이론 중 하나이기 때문에 방법론에 대한 개선 사항은 모든 후속 작업에서 재사용됩니다. 사람들은 여전히 이 시스템의 많은 작업을 수행하고 있으며, 그 작업은 계산(computation) 쪽으로 이동하고 있습니다.
이 저장소는 채택된 원칙(doctrine), 이를 반박할 수 있는 연구 및 증거, 그리고 도구를 담고 있습니다. 이 도구란 사용자가 자신의 프로젝트에서 동일한 종류의 지식 기반을 구축하기 위해 설치할 수 있는 유형(types), 규칙(conventions), 기술(skills), 스키마(schemas), 검증기(validators), 테스트(tests), 명령(commands) 등을 의미합니다. 연구는 단순히 여기에 저장된다고 해서 원칙이 되는 것은 아닙니다. 이 README는 도구에 대해 다루며, 아래의 연구 경로는 나머지 내용을 가리킵니다.
사용하기 (Use it)
프로젝트에 Commonplace 설치하기
명령줄 도구(command-line tool)를 OS 사용자당 한 번 설치합니다:
uv tool install --python ">=3.11" llm-commonplace
uv tool update-shell
셸 또는 에이전트 런타임(agent runtime)을 재시작한 후, 현재 프로젝트를 초기화합니다:
commonplace-init --root .
생성된 AGENTS.md.template 파일을 채워 프로젝트의 AGENTS.md로 사용하고, CLAUDE.md.template 파일은 CLAUDE.md로 이름을 변경합니다. 이 설치 과정은 Commonplace 유형, 규칙, 기술 및 명령을 제공하며, 프로젝트는 이를 복사하는 대신 설치된 패키지에서 직접 읽어옵니다. 따라서 새로운 지식 기반은 자체 프로젝트에 대한 지식을 축적하게 됩니다. 이 패키지에는 이 저장소의 외부 시스템 검토 내용이나 소스 코퍼스(source corpus)가 포함되어 있지 않습니다. INSTALL.md를 참조하십시오.
연구 자료를 읽기 전용으로 제공하기 (Vendor the research read-only)
에이전트가 Commonplace 시스템을 설치하지 않고도 전체 연구 코퍼스를 참고할 수 있도록 하려면, 이 저장소를 프로젝트 내부에 서브모듈(submodule)로 배치하거나 클론(clone), 복사하여 붙여넣은 다음, 프로젝트의 에이전트 지침서에 AGENTS.md.reader-fragment를 추가합니다. 리더 모드(Reader mode)는 Python이 필요 없으며, 에이전트 런타임에는 파일 접근 및 rg만 있으면 됩니다. Reader install를 참조하십시오.
Commonplace 개발하기 (Develop Commonplace)
git clone https://github.com/zby/commonplace.git
cd commonplace
uv tool install --python ">=3.11" --editable .
...
명령 경로(command path)의 소비자들을 재시작합니다. 일반적인 소스 변경 사항은 편집 가능한 설치(editable installation)를 통해 확인할 수 있습니다. 의존성(dependency), 진입점(entry-point), 빌드 메타데이터(build-metadata), 또는 패키징된 스캐폴드(packaged-scaffold)가 변경된 후에는 uv tool install --reinstall --python ">=3.11" --editable . 명령어로 재설치하십시오. 개발 검사는 uv run pytest와 uv run ruff check .로 실행합니다. 소스 체크아웃에서 commonplace-init을 실행하지 마십시오.
uv run pytest는 slow로 표시된 비용이 많이 드는 분석 워크플로우 테스트를 제외합니다. 해당 테스트를 사용하려면 uv run pytest -m slow를, 전체 스위트(complete suite)를 사용하려면 uv run pytest -m ""를 사용하십시오. CI 환경에서는 전체 스위트를 실행합니다. 분석 워크플로우나 그 수용 검사(acceptance checks)가 변경될 때만 느린 테스트를 실행하십시오.
구성 요소 (What's in the box)
kb/ 지식 기반 (Knowledge base)
theory/ 전이 가능한 연구 주장 및 이론 (Transferable research claims and theory)
articles/ 독립적인 기술 설명 문서 (Self-standing technical explanations)
...
핵심 설계 선택 사항 (Core design choices)
주장들은 네트워크를 형성합니다. 여기서 제목(titles)은 주제(topics)가 아니라 주장(assertions)이며, 링크는 주장이 어떻게 관련되는지—예: grounds(근거), extends(확장), contradicts(모순됨), 또는 exemplifies(예시함)—를 명시합니다. 이로 인해 탐색 과정이 일반적인 브라우징이라기보다는 일종의 추론(reasoning) 형태가 됩니다. 주장을 제목으로 사용하기와 링크 방법론를 참조하십시오.
구조는 점진적으로 얻어집니다. 프런트매터(frontmatter)가 없는 파일은 유효한 text입니다. 자료에 지속 가능한 주장이 필요할 때 설명을 추가하고 노트 유형을 지정하십시오. 더 전문화하는 것은 추가적인 계약(extra contract)이 유용한 작업을 가능하게 할 때만 하십시오. wikiwiki 원칙를 참조하십시오.
작성된 지식(Authored knowledge)은 파일 기반으로 유지됩니다. Markdown과 Git은 범용 인터페이스, 버전 관리, diff, 그리고 롤백 기능을 제공합니다. 파생 인덱스(Derived indexes)는 작성된 파일을 대체하지 않으면서 확장성을 처리합니다. 실행 상태 검토(Review execution state)는 범위가 지정된 예외이며 SQLite에 저장됩니다; ADR 010 및 ADR 035를 참조하세요.
로컬 계약(Local contracts)은 수정 가능하게 유지됩니다. 지식 기반의 여러 부분은 서로 다른 종류의 작업을 지원하므로, 작업별 유형(task-specific types)과 링크 규칙(link conventions)은 각 부분에 국한되어 유지됩니다. 질문, 증거 또는 모델 기능이 변경됨에 따라 구조도 구식이 될 수 있으므로, 이러한 로컬 선택 사항들은 수정 가능하게 유지됩니다. 공유 규칙(Shared rules)은 여러 부분을 가로질러 그리고 시간이 지나도 유지되는 제약 조건들을 위해 보존됩니다. task-fitted structure costs cross-task reuse를 참조하여 이유를 확인하세요.
원칙(Doctrine)은 명시적이며, 정확한 작업(exact operations)은 코드로 이루어집니다. 기술(Skills)과 규칙(conventions)은 모델에게 무엇을 해야 하고 어떤 기능을 사용해야 하는지 알려줍니다. 코드, 스키마, 검증기(validators)는 반복적인 해석에 의존해서는 안 되는 동작을 가진 작업을 담고 있습니다. 왜냐하면 코드는 [executes them the same way every time]이기 때문입니다. 양쪽 모두 증거와 모델 기능이 변경됨에 따라 수정 가능하게 유지됩니다.
연구 경로(Research routes)
rendered site는 연구로 진입하는 주요 경로입니다. 시작점:
- [이론 구축기 정의 (theory builder definition)]와 [Commonplace가 이론 구축기를 만들고 학습 여부를 테스트하는 방법 (commonplace-builds-a-theory-builder-and-tests-whether-it-learns)] — 이론 구축기가 무엇인지, 그리고 그것이 학습하는지 테스트하는 연구 프로그램에 대한 내용입니다.
- [배포 시점 학습 (deployment-time learning)]과 [학습 이론 인덱스 (learning theory index)] — 모델 가중치를 업데이트하지 않고도 후속 세션에 영향을 미치는 프롬프트, 규칙, 도구 및 코드의 영구적인 변경 사항입니다.
- [자체 개선 시스템 (self-improving systems)]과 [반성적 시스템으로서의 Commonplace (commonplace as a reflective system)].
- [에이전트 메모리 시스템 (agent memory systems)] 및 [에이전틱 시스템 (agentic systems)]에 대한 검토와, 이를 비교한 [비교 검토 (comparative review)]가 포함되어 있습니다.
명령어(Commands), 스킬(skills), 및 지침(instructions)
명령어는 이름으로 호출되는 결정론적 Python 진입점입니다. 예시:
commonplace-validate kb/theory
commonplace-init --root .
commonplace-github-snapshot https://github.com/owner/repo/issues/123
검토 시스템은 타겟 선택, 작업 대기열화(queuing jobs), 출력 최종 확정을 위한 명령어를 추가합니다. commonplace-x-snapshot을 사용하려면 snapshot 패키지 확장 기능이 필요합니다. [검토 시스템 개요 (review system overview)]를 참조하십시오.
스킬(cp-skill-*)은 작업이 해당 스킬의 설명과 일치할 때 호환 가능한 하네스(harnesses)에 의해 자동으로 로드되는 에이전트 절차입니다. 이들은 설치된 패키지에 남아 있으며, commonplace-init은 각 스킬에 대해 소비하는 프로젝트의 스킬 디렉터리에 작은 스텁(stub)을 작성하여 에이전트를 실제 스킬로 안내합니다.
| 스킬 (Skill) | 목적 (Purpose) |
|---|
cp-skill-write | 컬렉션 및 타입 계약 하에 아티팩트를 작성하거나 편집합니다. |
| ... | |
지침(Instructions)은 자동으로 로드되는 것이 아니라 명시적으로 호출되는 마크다운 절차입니다. 이들은 kb/instructions/ 아래에 위치합니다.
전제 조건 (Prerequisites)
리더 모드(Reader mode)는 프로젝트 파일 접근 권한과 rg가 있는 에이전트 런타임만 필요합니다. 전체 설치에는 다음 도구들이 사용됩니다:
| 도구 (Tool) | 필수 여부 (Required) | 목적 (Purpose) |
|---|
| 에이전트 런타임 (Agent runtime) | 예 (yes) | 프로젝트 지침을 로드하고 설치된 스킬을 노출합니다. |
| ... | | |
라이선스 (License)
Commonplace는 이중 라이선스(dual-licensed)를 사용합니다:
src/의 코드 및 패키징 도구 (tooling): MIT- 지식 기반(Knowledge-base) 콘텐츠, 문서화, 템플릿 및 번들링된 교육용 아티팩트: CC BY 4.0