Keystone: Project Harness Installer

저는 새로운 도구를 만들었습니다. 이것은 Level 2 프로젝트 하네스 설치기 (Level 3로 모호하게 넘어갑니다)입니다. 페이지는 tacoda.dev/keystone에 있으며, 저장소(repo)는 github.com/tacoda/keystone에 있습니다.

기능

keystone init은 여러분의 저장소에 마크다운 하네스 (markdown harness)를 생성합니다. 다섯 가지 계층이 있습니다: 원칙 (principles), 관용구 (idioms), 도메인 (domain), 상태 (state), 프로세스 (process). 또한 에이전트 (agent)가 가장 먼저 읽는 활성화 파일이 포함됩니다: Claude Code를 위한 CLAUDE.md, Codex CLI를 위한 AGENTS.md, Cursor를 위한 .cursor/rules/000-harness.mdc입니다.

init 이후에는 바이너리 (binary) 작업이 완료됩니다. 하네스는 여러분의 것입니다. 이것은 여러분의 저장소에 체크인(checked in)되고, 여러분이 편집하며, 여러분의 팀이 소유하는 일반적인 마크다운 파일입니다. Keystone은 런타임 의존성 (runtime dependency)이 아닙니다. 이것은 아티팩트 (artifacts)를 전달하고 떠나는 스캐폴더 (scaffolder)입니다.

설치는 하나의 바이너리로 이루어집니다. 다음 중 하나를 선택하세요:

brew install tacoda/tap/keystone

또는 curl 부트스트랩 (bootstrap):

curl -fsSL https://raw.githubusercontent.com/tacoda/keystone/main/install.sh | sh

keystone init은 프로젝트당 한 번 실행됩니다.

설정(config)이 아닌 코퍼스(corpus)로서의 하네스

설정 파일 (config file)은 에이전트에게 무엇을 할지 알려줍니다. 코퍼스 (corpus)는 에이전트에게 이것이 어떤 종류의 코드인지 알려줍니다. 그 차이는 체크리스트 (checklist)와 어휘 (vocabulary)의 차이와 같습니다.

다섯 가지 계층은 다섯 가지 서로 다른 질문에 답합니다.

• 원칙 (Principles). 스택 (stack)과 상관없이 좋은 엔지니어링이란 어떤 모습인가?
• 관용구 (Idioms). 이 스택은 어떻게 그 원칙들을 표현하는가?
• 도메인 (Domain). 어떤 비즈니스 규칙이 이 코드베이스 (codebase)를 제약하는가?
• 상태 (State). 현재 코드베이스에 대해 무엇이 사실인가?
• 프로세스 (Process). 워크플로 (workflow)의 각 단계에서 어떤 일이 일어나는가?

원칙은 프로젝트 간에 이동합니다. 관용구는 여러분의 스택 범위 내로 한정됩니다. 도메인과 상태는 부트스트랩 (bootstrap) 과정 동안 여러분과 에이전트가 함께 작성합니다. 프로세스는 명세 (spec), 계획 (planning), 구현 (implementation), 검증 (verification), 리뷰 (review), 출시 (release)의 6단계를 유지합니다.

에이전트(agent)는 관련 있는 내용만을 읽습니다. 하네스(harness)는 모든 것을 한꺼번에 로드하지 않습니다. 프로세스 파일(process files)은 해당 단계에 진입할 때 로드되며, 이디엄 파일(idiom files)은 지역(region)별로 지연 로딩(lazy load)됩니다. 이것이 바로 규율(discipline)입니다. 매 턴마다 토큰(token) 비용을 지불해야 하는 거대한 CLAUDE.md는 이 시스템이 방지하기 위해 구축된 실패 모드(failure mode)입니다.

하네스를 유지시키는 두 개의 플라이휠 (flywheels)

하네스는 정적이지 않습니다. 그것은 성장합니다.

학습 (Learning) 플라이휠은 머지(merge) 후에 실행됩니다. 에이전트는 변경 사항으로부터 패턴을 명명하고 learning/에 추가할 것을 제안합니다. 사용자는 이를 코퍼스(corpus)로 승격시킬지 결정합니다.

가지치기 (Pruning) 플라이휠은 감사(audit) 시 실행됩니다. 더 이상 적용되지 않는 규칙들은 그 근거(reasoning)와 함께 아카이브(archive)됩니다. 이를 통해 코퍼스가 6개월 전에는 타당했지만 지금은 방해가 될 뿐인 규칙들의 목록으로 석회화(calcify)되는 것을 방지합니다.

이것들은 제가 몇 달 동안 글을 써온 움직임들입니다. Keystone은 그것들이 실제로 구현된 모습입니다.

수행하지 않는 것들

이것은 실행(run)되지 않습니다. 데몬(daemon), 훅(hook), 백그라운드 프로세스(background process)가 없습니다. 바이너리(binary)는 스캐폴딩(scaffold)을 수행하고 종료됩니다.

에이전트를 대신 선택해주지 않습니다. 탐지(detection) 단계에서는 이미 저장소(repo)에 있는 마커 파일(CLAUDE.md, AGENTS.md, .cursor/ 등)을 읽습니다. 대화형으로 선택하거나 --agent 플래그를 전달하여 선택할 수 있습니다. 하네스는 에이전트 불가지론적(agent-agnostic)입니다. 에이전트마다 활성화 파일(activation file)과 어댑터(adapter) 디렉토리만 변경될 뿐입니다.

사용자를 종속시키지 않습니다. 초기화(init) 후에는 바이너리가 사라집니다. 하네스는 마크다운(markdown)입니다. 만약 내일 Keystone이 사라지더라도 당신의 프로젝트는 눈치채지 못할 것입니다.

어댑터(adapters)의 현황

Claude Code, Codex CLI, pi.dev 어댑터는 실제 구현되어 있습니다. Cursor, Aider, Copilot CLI, Continue, Cline, Goose는 스텁(stub) 형태로 제공됩니다. 즉, 시작하기에 충분한 최소한의 라이프사이클(lifecycle) 파일과 작동하는 메뉴만 포함되어 있습니다. 현재 스텁으로 나열된 에이전트에 대해 실제 어댑터를 작성한다면, 다시 기여(contribute)해 주세요. 구조는 harness/adapters/README.md에 문서화되어 있습니다: 에이전트당 하나의 lifecycle.md, sensors.md, activation.md가 필요하며, targets/<agent>/ 아래에 타겟 디렉토리가 있어야 합니다.

해당 페이지는 tacoda.dev/keystone에 있으며, 저장소(repo)는 github.com/tacoda/keystone에 있습니다.

제가 계속해서 되풀이하는 생각은 이것입니다: 하네스(harness)는 도구(tool)가 아니라 산출물(artifact)이라는 점입니다. Keystone은 제가 아는 한 훌륭한 하네스를 구축할 수 있는 가장 저렴한 방법입니다. 그 이후에는 프로젝트가 이를 소유하게 됩니다.