Agent Lab Journal

    Guides
...

      레벨: intermediate
      읽기 및 실습 시간: 75분
      결과물: 설치된 기술 세트(skill set) 및 리뷰 완결성, 테스트 품질, 실행 시간, 컨텍스트(context) 사용량을 포함하는 비교 보고서
...

      모델, 저장소(repository), 작업(task), 사용 가능한 도구들을 변경하지 않은 상태에서 동일한 코딩 에이전트의 두 가지 모드를 비교하게 됩니다:

        명시적인 스킬 (Explicit skills)은 작업을 더 완전하고 반복 가능하게 만들어야 합니다. 또한 에이전트의 컨텍스트 (context)에 지침을 추가하므로 실행 시간을 증가시킬 수 있습니다. 스킬은 측정된 품질 이득이 테스트한 작업 클래스에 대해 해당 비용을 정당화할 때만 유용합니다.

      범용 에이전트는 코드를 읽고, 명령을 실행하며, 파일을 편집하고, 패치 (patch)를 설명할 수 있습니다. 하지만 "철저하게 수행하라"는 말은 어떤 검사가 필수적인지를 정의하지 않습니다. 어떤 실행은 테스트로 시작할 수 있고, 다른 실행은 구현으로 시작할 수 있으며, 세 번째 실행은 가능한 결함을 설명한 후 멈출 수도 있습니다.

      이 실험실 (laboratory)에서 스킬 (skill)은 활성화 조건, 일련의 동작, 완료 기준 및 금지 사항을 포함하는 버전 관리된 작은 문서입니다. 이는 별도의 모델도 아니고 숨겨진 지식 베이스 (knowledge base)도 아닙니다. 에이전트가 이미 가지고 있는 역량을 조직화하는 것입니다.
...

      유용한 비교 작업은 코드, 테스트, 그리고 공개 문서를 포함해야 합니다. 작은 학습용 서비스(training service)를 사용하거나 본인의 저장소 (repository)에서 유사한 크기의 모듈을 격리하여 사용하십시오. 예시 함수는 주문의 모든 항목을 예약합니다:

def reserve_order(inventory, order):
    reserved = []

...

이 요구사항들은 평가자의 참조 시트(reference sheet)를 구성합니다. 에이전트에게 이 시트를 주지 마십시오. 그렇지 않으면, 실험은 기술의 가치 대신 제공된 체크리스트를 재현하는 능력을 측정하게 됩니다. 당신의 작업(task)을 위해, 첫 번째 실행 전에 그와 동등한 참조 시트를 작성하십시오.

변경 사항은 두 번 실행할 수 있을 만큼 충분히 작지만, 여러 종류의 추론(reasoning)을 요구합니다. 피상적인 응답은 성공적인 주문 테스트만 추가할 수 있습니다. 더 완전한 검토는 부분적인 부작용(side effect), 중복 항목, 수량 검증, 그리고 실패 계약(failure contract)을 문서화할 필요성을 식별할 수 있습니다.

로컬 테스트 픽스처(test fixtures)와 가짜 재고 어댑터(fake inventory adapter)를 사용하십시오. 운영 환경의 자격 증명(credentials), 실제 고객 데이터, 또는 통제되지 않은 네트워크 의존성을 포함하지 마십시오.

비교를 작은 벤치마크(benchmark)로 취급하십시오. 기술의 가용성(availability)이 모드 간의 유일한 의도적인 차이점이어야 합니다.

      두 모드를 동일한 작업 디렉토리에서 순차적으로 실행하지 마십시오. 두 번째 실행은 첫 번째 실행의 코드, 테스트, 노트 또는 로그를 볼 수 없어야 합니다.

mkdir -p experiment
git rev-parse HEAD > experiment/base-sha.txt

...

      프로젝트 수준의 기술(skills)이 저장소 내에 존재해야 하는 경우, 두 워크트리 외부 모두에 저장하거나, 해당 기술을 포함하는 공통 커밋을 생성한 뒤 모드 A에서 해당 기술의 로딩을 명시적으로 비활성화하십시오. 보고서에 정확한 비활성화 메커니즘을 기록하십시오.

      한 쌍의 경우, A를 실행한 후 B를 실행하고 그 순서를 기록하십시오. 더 큰 데이터 세트의 경우, 이를 교차하십시오: 첫 번째 작업은 A–B, 두 번째 작업은 B–A로 진행합니다. 이는 데워진 캐시(warm caches), 제공자 부하(provider load), 그리고 평가자가 이전 응답을 기억하는 것으로 인한 편향(bias)을 줄여줍니다.

      어느 쪽의 결과도 확인하기 전에 모든 채점 규칙을 정의하십시오. 그렇지 않으면, 잘 다듬어진 답변이 평가자가 중요하다고 생각하는 요소를 무의식적으로 변화시킬 수 있습니다.

id,requirement,weight,evidence_rule
R1,"나중에 발생한 실패 후 이전 예약 사항 보상",3,"부분 예약 시나리오를 명시하고 책임이 있는 코드를 지목함"
R2,"양의 정수 수량 검증",2,"최소 하나 이상의 구체적인 잘못된 입력을 식별함"
...

      가중치 3은 데이터 무결성(data-integrity) 위험을 나타내고, 가중치 2는 중요한 동작을 나타내며, 가중치 1은 계약의 완전성(contract completeness)을 나타냅니다. 답변을 확인한 후에는 가중치를 조정하지 마십시오.

### 문서화 품질 (Documentation quality)

  정확하게 문서화된 각 항목에 대해 1점을 부여합니다: 공개 엔트리 포인트 (public entry point), 유효한 입력 (valid input), 성공적인 결과 (successful result), 부분 실패 동작 (partial-failure behavior), 빈 주문 동작 (empty-order behavior), 그리고 테스트 명령 (test command). 문서화 점수의 최대치는 6점입니다.

## 세 가지 기술 세트 (The three-skill set)

  기술의 위치와 매니페스트 (manifest)는 에이전트마다 다릅니다. 아래의 이식 가능한 구조는 기술당 하나의 디렉토리를 사용하며, 메타데이터와 지침이 포함된 SKILL.md 파일을 사용합니다. 만약 사용 중인 환경이 다른 매니페스트를 사용한다면, 활성화 조건과 절차를 그대로 유지하십시오.

### 기술 1: 증거 기반 코드 리뷰 (Skill 1: evidence-based code review)

skills-src/evidence-code-review/SKILL.md 파일을 생성합니다:

### 기술 2: 행동 중심 테스트 설계 (Skill 2: behavior-oriented test design)

skills-src/behavior-test-design/SKILL.md 파일을 생성합니다:

### 기술 3: 계약 문서 동기화 (Skill 3: contract documentation synchronization)

skills-src/contract-doc-sync/SKILL.md 파일을 생성합니다:

  파일들은 의도적으로 짧게 작성되었습니다. 아키텍처, 보안, Git, 테스트 및 문서화를 한꺼번에 제어하는 기술은 또 다른 모호한 전역 프롬프트 (global prompt)가 되어버립니다.

## 설치 및 탐색 (Installation and discovery)

  사용 중인 에이전트에 대해 문서화된 사용자 수준 또는 프로젝트 수준의 기술 디렉토리를 찾으십시오. 추측하지 마십시오. 어떤 에이전트는 리포지토리에서 직접 기술을 읽고, 어떤 에이전트는 사용자 디렉토리를 사용하며, 어떤 에이전트는 설정에 등록이 필요합니다.

만약 에이전트가 .agent/skills를 지원한다면, 설치는 다음과 같이 진행될 수 있습니다:

해당 명령은 정확히 세 개의 경로를 출력해야 합니다:

  다음으로, 에이전트가 지원하는 기술 목록 확인 (skill-listing) 명령 또는 인터페이스를 사용하십시오. 실제 명령과 그 출력값을 기록하십시오. 다른 제품의 예시 명령으로 대체하지 마십시오.

### 파일 존재 여부뿐만 아니라 활성화 여부를 확인하십시오

  파일이 올바른 위치에 있더라도 잘못된 메타데이터 (metadata) 때문에 무시될 수 있습니다. 에이전트에게 읽기 전용 진단 요청을 보내십시오: “리뷰, 테스트 및 문서화가 포함된 작업에 적용 가능한 사용 가능한 기술은 무엇입니까? 파일을 변경하지 말고 이름만 말해 주세요.”

  모드 B (Mode B)는 설치된 세 가지 이름을 모두 식별해야 합니다. 모드 A (Mode A)는 이를 노출해서는 안 됩니다. 두 진단 응답을 모두 저장하십시오. 만약 두 모드가 동일한 기술을 본다면, 중단하십시오. 의도된 처리가 적용되지 않은 것입니다.

## 모드 A (Mode A): 범용 에이전트 실행

  기술이 없는 실행 (unskilled run)을 베이스라인 (baseline)으로 취급하십시오. 해당 워크트리 (worktree)로 진입하여 시작 커밋 (starting commit)을 확인하고, 기존 스위트 (suite)가 통과 (green) 상태인지 확인하십시오:

  만약 시작 스위트가 이미 실패한다면, 알려진 실패 사항을 기록하거나 다른 커밋을 선택하십시오. 기존에 존재하던 실패를 어느 에이전트 모드의 탓으로 돌리지 마십시오.

작업을 하나의 불변 파일 (immutable file)에 저장하십시오:

  추가적인 힌트 없이 experiment/task.txt의 정확한 내용을 전송하십시오. 전체 응답, 패치 (patch), 명령 로그 (command log), 모델 식별자 (model identifier), 실행 시간 제한 (runtime limits), 그리고 환경에 의해 노출된 사용 정보 (usage information)를 모두 저장하십시오.

## 모드 B (Mode B): 기술이 장착된 에이전트 실행

  숙련된 워크트리 (skilled worktree)에서 동일한 준비 과정을 반복합니다. 초기 SHA가 기록된 베이스 (base)와 일치하는지, 그리고 세 가지 기술 (skills)을 발견할 수 있는지 확인합니다.

## 시간 및 컨텍스트 사용량 측정 (Measure time and context usage)

  에이전트 런타임 (agent runtime)에서 출력되는 타임스탬프 (timestamps)를 우선적으로 사용합니다. 사용할 수 없는 경우, 전체 호출을 단조 타이머 (monotonic timer) 또는 GNU time으로 감싸십시오.

### "컨텍스트 사용량 (context usage)"의 의미

값들을 병합하지 말고 각각의 별도 값을 기록하십시오: