About

개요: Origemite Archive는 작성자가 쓰는 기술 결정, 코드 스타일, 구현 기준을 한 곳(SSOT)에 등록하고, AI 하네스가 그것을 계속 꺼내 쓰게 하기 위한 개인 엔지니어링 아카이브입니다.

왜 만들었는지​

개발하면서 내린 결정과 굳어진 코드 스타일은 머릿속, 지난 프로젝트, 흩어진 메모에 남습니다. 새 프로젝트를 시작하거나 AI 코딩 에이전트에게 일을 맡길 때마다 그것을 다시 설명해야 했습니다.

이 아카이브는 그 반복을 없애기 위한 것입니다.

• 작성자가 주로 쓰는 코드 스타일과 구현 기준을 Markdown으로 등록합니다.
• 왜 그렇게 정했는지를 ADR과 History로 남깁니다.
• 하네스가 상황에 맞는 문서와 템플릿만 골라 에이전트에게 전달합니다.

한 번 쓰고, 사람과 AI가 계속 씁니다.

무엇을 담는지​

Knowledge는 큰 개념과 설계 기준입니다. Master가 판단이 필요한 상황에서 설계 원칙과 함께 봅니다. Template은 임플리먼터가 구현하는 고정된 코드 구조입니다. 적용 가능한 템플릿이 있으면 임플리먼터는 그 모양대로 구현합니다. 없으면 저장소의 기존 구현 패턴을 따릅니다. 둘 다 없으면 승인된 범위 안에서 최소 구현을 합니다. 새 계층, 공개 계약, 의존성, 아키텍처 결정이 필요하면 Master가 정한 뒤에 진행합니다. 템플릿이 없다는 이유만으로 구현을 멈추지 않습니다.

단일 출처 (SSOT)​

원본은 Markdown + Git입니다. Docusaurus는 사람이 읽기 위한 화면일 뿐입니다.

• 사이트가 바뀌어도, AI 제품이 바뀌어도 자산은 그대로 남습니다.
• 사이드바나 카테고리 설정은 탐색용이며, 엔지니어링 의미를 정의하지 않습니다.
• 규칙이 충돌하면 순서가 있습니다: 프로젝트 로컬 규칙 → 현재 하네스 기준 → Profile → 채택된 ADR → Template → 일반 관행.

하네스가 쓰는 방식​

에이전트는 아카이브 전체를 읽지 않습니다.

요청
  → Master가 상황을 분류
  → 상황에 맞는 Orchestration(어떤 역할 + 어떤 문서)을 선택
      없으면 빈칸을 알리고 레시피를 작성
  → 워커는 그 레시피에 적힌 문서와 템플릿만 읽고 작업

그래서 코드 스타일을 한 번 등록해 두면, Cursor든 Codex든 Claude Code든 같은 기준으로 코드를 냅니다. 에이전트 입구는 저장소 루트의 AGENTS.md와 index/입니다.

에이전트는 미리 세팅해 둡니다​

역할별 에이전트를 docs/harness/agents/에 하나씩 정의해 둡니다. 매번 프롬프트를 새로 쓰지 않습니다.

Implementer만 낮음에 둡니다. 등록한 코드 스타일대로 코드를 내는 역할이라 가장 강하게 규제합니다. 검증하는 역할들은 판단할 여지가 필요해서 한 단계 위에 둡니다.

역할 문서는 책임입니다. 매번 모든 역할을 별도 에이전트로 실행하지 않습니다. 익숙한 저장소의 기존 패턴은 기본 흐름만 사용합니다.

• Scout은 낯선 저장소에 들어갈 때 먼저 갑니다. 스택, 폴더 구조, 프로젝트 로컬 규칙, 테스트 실행 방법, 아카이브 템플릿과 다른 점을 한 화면짜리 지도로 만들어 Master에게 줍니다. 파일은 절대 바꾸지 않습니다. 비싼 Master가 파일을 뒤지며 토큰을 쓰지 않게 하는 역할입니다.
• Curator는 사용자가 승격을 요청할 때만 갑니다. 프로젝트에서 반복된 코드와 결정 중 기준이 될 만한 것을 골라 도메인과 비밀을 벗기고 Template, Knowledge, ADR 형태로 옮긴 뒤 Index와 History를 맞춥니다. 반복됐거나, 작성자가 "이렇게 합니다"라고 말했거나, Postmortem에서 나온 것만 올립니다. 한 번 쓴 코드는 Experiments에 머뭅니다. 올릴지 말지의 최종 결정은 Master와 작성자가 합니다.

역할은 아무도 맡지 않은 질문이 생길 때만 늘립니다. 보안 리뷰나 성능 테스트처럼 질문은 같고 체크리스트만 다른 것은 기존 역할에 미션 라벨을 붙여 처리합니다.

각 에이전트 문서에는 세 가지가 들어갑니다.

• 역할 계약: 하는 것, 하지 않는 것, 반환 형식
• 모델 풀: 하나의 모델에 고정하지 않고 우선순위 목록을 둡니다. 제품이 바뀌어 슬러그가 사라져도 다음 후보로 넘어갑니다. Master만 강한 모델을 쓰고, 워커는 비용이 낮은 모델을 씁니다. 검증은 Master가 다시 합니다.
• 자유도: 모인 컨텍스트에서 얼마나 벗어나도 되는지를 역할마다 다르게 둡니다.
  • 낮음: 적힌 대로 따릅니다. 템플릿을 복사하고 빈칸만 채우며, 모르면 BLOCKED로 돌려보냅니다. 대안 설계나 "더 나은 방법"은 금지합니다.
  • 중간: 컨텍스트가 허용하는 범위 안에서 판단합니다. 어떤 테스트 단계를 돌릴지, 지적의 심각도를 어떻게 매길지 정도입니다.
  • 높음: 질문하고, 반박하고, 레시피를 새로 씁니다. 작성자와 계속 대화하는 쪽이라 Master만 여기 둡니다.

오케스트레이션 파일은 역할의 자유도를 낮출 수만 있고 올릴 수는 없습니다.

오케스트레이션은 상황마다 나눕니다​

흩어져 있는 자료를 한 덩어리로 묶지 않습니다. 상황 하나당 오케스트레이션 MD 파일 하나를 둡니다. 각 파일은 그 상황에 필요한 것만 인덱싱합니다.

• 어떤 역할을 어떤 순서로 부를지
• 어떤 Knowledge 문서를 읽을지
• 어떤 템플릿을 기준으로 삼을지. 가장 최근에 정리한 코드 예제가 여기 연결됩니다.
• 성공 기준과 제약

예를 들어 spring-api-one-set은 테이블 한 세트를 ExampleItem 템플릿으로 추가하는 상황입니다. 통과 기준은 템플릿 기준을 재사용하고, 구현과 관련 테스트를 한 흐름에서 합니다.

같은 방식으로 spring-bugfix, spring-refactor-layer, archive-promote-pattern 같은 파일이 따로 있습니다. 별도 에이전트 조건은 기본 흐름 문서 한 곳에 있습니다.

Master는 같은 상황의 레시피가 있으면 재사용합니다. 없으면 기본 흐름으로 진행합니다. 새 레시피는 그 상황이 반복될 때만 제안합니다.

흩어진 자료
  Knowledge, Templates, ADR, Patterns
        ↓ 인덱싱
오케스트레이션 MD 파일들
  spring-api-one-set.md, spring-bugfix.md, …
        ↓ 같은 상황이면 재사용, 아니면 기본 흐름
범위와 통과 기준, 규칙 및 템플릿, 구현과 테스트, 검증, 짧은 기록, 승인된 경우 커밋
        ↓ 별도 에이전트는 기본 흐름 문서의 조건일 때만

새 코드 예제가 정리되면 템플릿을 갱신하고, 오케스트레이션 파일의 링크만 바꿉니다. 에이전트 프롬프트는 건드리지 않습니다.

통과 가능한 코딩의 기준​

이 하네스의 중요 기준입니다. 구현 전에 기대 결과와 완료 기준을 정합니다. 모든 작업에 테스트 선작성이나 실패, 통과, 정리를 강제하지 않습니다.

적용 가능한 템플릿이 있으면 그 구조, 메서드 목록, DTO 형태, 계층 책임을 지킵니다. 없으면 저장소의 기존 패턴을 따르고, 그것도 없으면 승인된 범위의 최소 구현을 합니다. 새 계층, 공개 계약, 의존성, 아키텍처 결정만 선택지와 영향을 본 뒤에 진행합니다. 재사용할 발견은 후보로 보고하고, 문서 갱신은 사용자가 요청할 때 합니다.

완료는 테스트 통과만이 아닙니다. 요구사항을 충족했는지, 기존 동작이 회귀하지 않았는지를 함께 봅니다. 본문은 구현 전 통과 기준입니다.

바이브 코딩은 검증 도구와 함께 갑니다​

이 아카이브는 바이브 코딩을 허용합니다. 대신 AI가 제대로 바이브 코딩을 했는지 AI 스스로 검증할 수 있는 도구를 제공하는 방법을 같이 제공합니다. 빠르게 쓰는 것과 맞는지 확인하는 것은 한 묶음이고, 확인 없는 "잘 된 것 같다"는 결과로 치지 않습니다.

검증 도구는 docs/harness/tools/에 카탈로그로 등록합니다.

기본 경로에서는 구현 담당이 필요한 테스트를 작성하고 실행하며 결과를 확인합니다. 등록된 도구로만 증명합니다. 도구를 실행할 수 없으면 구현 결함과 구분하고, 가짜 PASS를 하지 않습니다. 테스트 통과만으로 요청 충족을 단정하지 않습니다.

도구가 무엇인지는 tools/에, 어느 스택에서 기본으로 무엇을 쓰는지는 Profile에, 이번 작업에 어떤 도구를 어느 단계까지 쓸지는 오케스트레이션 파일에, 크롬을 실제로 어떻게 여는지는 제품별 Entrypoint에 적습니다. 새 도구가 생기면 tools/에 파일 하나를 더하고 Profile 링크만 바꿉니다.

아카이브의 흐름​

프로젝트에서 반복되는 선택
  → Experiment
  → ADR (왜 이렇게 정했는지)
  → Knowledge / Pattern (기준으로 승격)
  → Template (코드 모양)
  → Harness가 다음 작업에 투입

실패나 장애는 Postmortem으로 들어와 같은 경로를 탑니다.