Macroscope

Macroscope는 에이전트 안에서 로컬 Macroscope 코드 리뷰를 실행해요. 도구 하나가 설치된 macroscope CLI를 셸로 호출하고, 스트리밍된 발견사항을 파싱해 구조화된 데이터로 반환하죠. 에이전트는 각 발견사항을 검증하고, 이미 가진 도구로 진짜 문제를 고쳐요. 이 capability는 발견사항만 표면화합니다.

Source

Pydantic AI Harness가 0.x 릴리스인 동안 API는 마이너 릴리스 사이에 바뀔 수 있어요. 바뀔 때는 폐기 경고와 릴리스 노트 마이그레이션 안내가 정확히 어떻게 업그레이드할지 알려줘요. 버전 정책 참고.

출처: 문서

본문

문제 (The problem)

Macroscope는 현재 브랜치의 diff를 리뷰하고 발견사항을 스트리밍하지만, 편집기 플러그인(Claude Code, Codex, Cursor, OpenCode)으로 배포돼요. Pydantic AI 에이전트에게 같은 리뷰-및-수정 루프를 당신의 코드에서 주는 방법이 없어요.

사용법 (Usage)

from pydantic_ai import Agent
from pydantic_ai_harness import Macroscope

agent = Agent('anthropic:claude-sonnet-5', capabilities=[Macroscope()])

result = agent.run_sync('Run a Macroscope review and fix any real findings.')
print(result.output)

macroscope CLI가 호스트에 먼저 설치·인증되어 있어야 해요:

설치: curl -sSL https://raw.githubusercontent.com/prassoai/macroscope-local/main/install.sh | bash
macroscope를 한 번 실행해 로그인하고 워크스페이스를 선택.

이 capability는 당신을 대신해 설치하거나 인증할 수 없어요. 바이너리가 없으면 도구는 설치 명령을 반환하고, 리뷰가 시작되지 않으면(보통 로그인하지 않아서) 도구는 에이전트에게 macroscope를 실행해 설정을 끝내라고 알려요.

도구는 머신이 읽을 수 있는 스트리밍 출력을 위해 macroscope codereview --raw를 호출하는데, 최근 CLI 빌드가 필요해요. 설치 프로그램이 최신 것을 가져오고 CLI가 사용 시 자체 업데이트하므로, 새 설치로 충족돼요.

도구 (The tool)

도구	용도
`run_macroscope_review`	현재 브랜치에서 `macroscope codereview`를 실행하고 리뷰 id·종료 상태·발견사항을 반환. 선택적 `base` git ref 받음

각 발견사항은 issue_id, sequence, path, line, severity, category, body를 가진 MacroscopeIssue예요. capability의 기본 지시문은 에이전트에게 모든 발견사항을 미신뢰로 취급하라고 말해요. 영향을 받은 코드를 읽어 문제가 진짜인지 확인하고, 오탐과 중복은 건너뛰고, 각 수정을 검증하라고요.

옵션 (Options)

Macroscope의 모든 필드와 기본값:

from pydantic_ai_harness import Macroscope

Macroscope(
    base=None,             # git ref to diff against -- None lets the CLI auto-detect
    command='macroscope',  # binary name or path
    cwd='.',               # repository directory the review runs in
    timeout=600.0,         # max seconds to wait for a review
    guidance=None,         # None = default instructions, '' = none, str = custom
)

호출별 base 인자가 필드보다 우선해요. 리뷰는 원격 서비스를 호출하므로 타임아웃은 기본적으로 관대해요. 타임아웃 시 CLI의 프로세스 그룹이 죽고, 타임아웃은 모델에게 재시도 가능한 오류로 보고돼요.

범위와 구성 (Scope and composition)

이 capability는 발견사항만 표면화해요. 파일을 편집·워크트리 생성·커밋하지 않아요. 발견사항을 검증·수정하는 것은 에이전트의 몫이고, 다른 capability들을 사용해요. 에이전트가 코드를 읽고 수정을 적용하게 하려면 FileSystem 또는 Shell과 짝지고, 수정이 작업 트리 밖에 머물길 원하면 격리된 워크트리에서 에이전트를 실행하는 걸 고려하세요.

에이전트 스펙 (Agent spec)

Macroscope는 Pydantic AI의 agent spec과 동작하므로, Python 대신 구성 파일에서 선언할 수 있어요:

# agent.yaml
model: anthropic:claude-sonnet-5
capabilities:
  - Macroscope:
      base: main
      timeout: 900

from pydantic_ai import Agent
from pydantic_ai_harness import Macroscope

agent = Agent.from_file('agent.yaml', custom_capability_types=[Macroscope])

스펙 로더가 Macroscope를 어떻게 인스턴스화할지 알도록 custom_capability_types를 넘기세요.

더 읽기 (Further reading)

API 참고 (API reference)

Macroscope

Bases: AbstractCapability[AgentDepsT]

macroscope CLI 코드 리뷰를 실행하고 발견사항을 에이전트에게 넘겨요.

macroscope codereview에 셸로 호출하고 스트리밍된 발견사항을 파싱해 MacroscopeReview로 반환하는 run_macroscope_review 도구를 추가해요. 에이전트는 자기 도구로 발견사항을 검증·수정해요. 이 capability는 파일 편집·워크트리 생성·커밋을 하지 않아요.

from pydantic_ai import Agent
from pydantic_ai_harness.macroscope import Macroscope

agent = Agent('anthropic:claude-sonnet-5', capabilities=[Macroscope()])

macroscope CLI는 호스트에 먼저 설치·인증되어 있어야 해요(패키지 README 참고). 이 capability는 사용자 대신 로그인할 수 없어요. 리뷰가 시작되지 않으면 도구는 사용자가 macroscope를 한 번 실행해야 한다고 보고해요.

속성 (Attributes)

base

diff할 git ref. None이면 --base가 생략되고 CLI가 베이스 브랜치를 스스로 자동 감지해요(그리고 자기 리뷰 워크트리를 만듦).

타입: str | None 기본: None

command

CLI 바이너리의 이름 또는 경로. 기본이 아닌 설치 위치에는 오버라이드.

타입: str 기본: 'macroscope'

cwd

리뷰가 실행되는 저장소 디렉터리.

타입: str | Path 기본: '.'

timeout

리뷰를 기다리는 최대 초. 리뷰는 원격 서비스를 호출하므로 기본적으로 관대함.

타입: float 기본: 600.0

guidance

시스템 프롬프트에 대한 커스텀 리뷰 안내.

기본 검증-후-수정 안내에 None으로 두거나, 어떤 지시문도 기여하지 않으려면 ''으로 설정.

타입: str | None 기본: None

메서드 (Methods)

get_toolset

def get_toolset() -> MacroscopeToolset[AgentDepsT]

run_macroscope_review 도구를 제공하는 toolset 구축.

반환

MacroscopeToolset[AgentDepsT]

get_instructions

def get_instructions() -> str | None

정적 검증-후-수정 안내.

비-None guidance가 기본값을 대체하고, ''은 지시문을 완전히 비활성화.

반환

str | None

MacroscopeReview

Bases: BaseModel

macroscope codereview 실행 하나의 결과.

status는 CLI가 보고한 종료 issue_status(completed 또는 failed)이고, 스트림이 하나 없이 끝나면 unknown이에요. review_id는 CLI가 하나를 방출하지 않았을 때(보통 리뷰가 시작되지 않아서) None이에요.

MacroscopeIssue

Bases: BaseModel

macroscope codereview가 스트리밍한 단일 발견사항.

관대하게 파싱돼요. 알 수 없는 필드는 무시되어 새 CLI 출력이 파싱을 깨지 않고, 필요한 필드가 없는 issue_event 줄은 건너뛰어요.

더 알아보기 (Learn more)

Macroscope CLI documentation — CLI 참고.
FileSystem / Shell — 수정 적용용.
Pydantic AI Harness — 패키지 전반.