Harness Config: AI 도구 설정을 위한 Source-to-Surface 모델

대부분의 저장소(Repository)는 현재 개발자들이 병행하여 사용하는 수많은 AI 코딩 도구의 수를 고려하여 설계되지 않았습니다.

하나의 저장소에는 Codex가 읽을 수 있는 지침을 위한 AGENTS.md, Claude 전용 설정을 위한 .claude/, Cursor 규칙을 위한 .cursor/, 또 다른 선언된 harness surface를 위한 .agents/가 있을 수 있으며, 여기에 프롬프트(Prompts), 기술(Skills), 훅(Hooks), 로컬 설정 및 도구별 런타임(Runtime) 파일들이 추가됩니다.

각 파일은 개별적으로는 의미가 있습니다. 각 도구는 지침을 읽어올 장소가 필요하기 때문입니다.

문제는 이러한 장소들이 서로 경쟁하는 '신뢰할 수 있는 단일 원천(Source of Truth)'이 될 때 시작됩니다.

하나의 규칙이 여러 폴더에 복사됩니다. 한 곳의 복사본은 변경되지만, 다른 곳은 변경되지 않습니다. 런타임(Runtime) 설정이 로컬에 작성된 후 실수로 커밋(Commit)됩니다. 팀별 오버라이드(Override)가 공유 프로젝트 설정처럼 보이기 시작합니다.

저장소는 여전히 작동하지만, 소유권이 불분명해집니다.

이것이 바로 Harness Config가 해결하고자 하는 드리프트(Drift) 문제입니다.

Harness Config에서 말하는 “Harness”의 의미

Harness Config는 몇 가지 용어를 신중하게 사용합니다.

Harness는 저장소의 지침, 컨텍스트(Context), 도구 및 설정을 소비하는 AI 에이전트(Agent) 또는 개발자 대상 도구의 런타임(Runtime)을 의미합니다.

Harness surface는 harness가 읽어들이는 저장소 로컬 파일 또는 폴더를 의미합니다. 예시는 다음과 같습니다:

AGENTS.md
.agents/
.claude/
.cursor/
기타 선언된 출력 위치

중요한 아이디어는 이러한 '라이브 surface(Live surfaces)'가 반드시 영구적인 소스(Durable source)일 필요는 없다는 점입니다.

이것들은 투영된 출력물(Projected outputs)이 될 수 있습니다.

Source-to-Surface 모델

Harness Config는 검토된 설정을 일반적으로 .harness/ 아래의 소스 레이아웃(Source layout)에 유지하고, 해당 소스를 선언된 harness surface로 투영(Projecting)할 것을 제안합니다.

쉽게 말하면 다음과 같습니다:

.harness/는 검토된 소스(Source)입니다.
투영(Projection)은 각 선언된 surface가 무엇을 받아야 하는지 계산합니다.
AGENTS.md, .agents/, .claude/, .cursor/ 및 유사한 위치들은 라이브 harness surface입니다.

소스는 작성되고 검토됩니다.

surface는 도구들이 읽는 대상입니다.

그 경계가 중요한 이유는 라이브 도구 폴더(live tool folders)에 검토된 설정(reviewed config), 투영된 출력(projected output), 로컬 설정(local settings), 그리고 런타임 소유 상태(runtime-owned state)가 혼합되어 있는 경우가 많기 때문입니다.

CLI 워크플로우 (The CLI Workflow)

CLI 또한 동일한 모델을 따릅니다.

매니페스트(manifest)는 구성된 소스(configured sources)와 선언된 서피스(declared surfaces)를 선언합니다. 그런 다음 CLI는 아무것도 작성하기 전에 저장소(repo)를 검증하고 활성화(activation)를 미리 보기 할 수 있습니다.

대략적인 워크플로우는 다음과 같습니다:

npx harnessc validate
npx harnessc activate
npx harnessc activate --yes

사고 모델(mental model)은 간단합니다:

validate는 설정을 확인합니다.
activate는 투영(projection)을 미리 보기 합니다.
activate --yes는 투영을 작성합니다.

그 미리 보기 단계는 중요합니다. 투영된 파일들이 업데이트되기 전에 변경 사항을 검사할 수 있게 해주기 때문입니다.

이것은 모든 도구를 위한 하나의 범용 설정이 아닙니다

서로 다른 AI 도구들은 서로 다른 설정이 필요합니다.

Codex, Claude, Cursor 및 기타 harness들은 모두 동일한 파일을 동일한 방식으로 소비하지 않습니다. 유용한 표준이라면 이러한 차이점을 숨기는 대신 허용해야 합니다.

Harness Config는 공유 리소스(shared resources), 타겟 특정 오버라이드(target-specific overrides), 프로필(profiles), 조합 가능한 지침 파일(composable instruction files), 그리고 가변 파일(mutable files)을 통해 이를 지원합니다.

즉, 다음과 같은 의미입니다:

공유 리소스는 계속 공유된 상태로 유지될 수 있습니다.
도구별 출력(tool-specific output)은 여전히 투영될 수 있습니다.
프로필을 통해 다양한 작업 모드에 따라 설정을 전환할 수 있습니다.
가변 파일은 한 번 시드(seeded)된 후 런타임(runtime)에 의해 소유될 수 있습니다.

핵심은 모든 도구를 동일하게 만드는 것이 아닙니다.

핵심은 소유권(ownership)을 가시화하는 것입니다.

이것이 중요한 이유

팀이 동일한 저장소(repository)에 더 많은 AI 코딩 도구를 추가함에 따라, 설정 드리프트(configuration drift)를 놓치기가 더 쉬워집니다.

소스-투-서피스(source-to-surface) 모델이 없다면, 새로운 도구가 추가될 때마다 지침(instructions)이 복사되거나, 변경되거나, 잊혀질 수 있는 또 다른 장소가 생겨나게 됩니다.

시간이 흐르면, 어떤 파일은 기술적으로는 여전히 유효할지 모르지만, 그것이 직접 편집되어야 하는 것인지, 다른 곳에서 투영된 것인지, 아니면 런타임에 의해 소유된 것인지 아무도 알 수 없게 됩니다.

투영 모델(projection model)을 사용하면, 저장소는 여전히 여러 harness를 지원할 수 있으면서도, 작성된 설정(authored configuration)은 더 명확한 위치를 가질 수 있습니다.

저는 협력자로서 이 저장소(repo)에서 작업해 왔으며, 제게 특히 눈에 띄는 부분은 다음과 같습니다: Harness Config는 도구들을 동일하게 강제하는 것이 아니라, 설정의 소유권(configuration ownership)을 명시적으로 만드는 것에 더 가깝습니다.

서로 다른 harness는 필요할 때 서로 다른 설정(config)을 가져야 합니다.

하지만 저장소는 어떤 파일이 검토 대상인 소스(reviewed source)인지, 어떤 파일이 투영된 표면(projected surfaces)인지, 그리고 어떤 파일이 런타임(runtime)에 속하는지를 명확히 해야 합니다.

그것이 바로 Harness Config가 정의하고자 하는 경계입니다.

저장소(Repo): https://github.com/reachjalil/harness-config

사양(Spec): https://www.harnessconfig.dev/