toki/oto
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oto/agent-roadmap/archive/phase/cli-automation-surface/milestones/structured-automation-surface.md
toki 807ca7fc6e refactor: agent-roadmap 구조로 마이그레이션 및 AI 에이전트 규칙 일원화 
- agent-ops/roadmap/를 agent-roadmap/으로 디렉터리 구조 재구성
- AI 에이전트별 ignore 파일 (.clineignore, .cursorignore, .geminiignore 등) 및
  규칙 파일 (.clinerules, .cursorrules, AGENTS.md 등) 통합
- agent-ops 스킬 템플릿 및 규칙 파일 업데이트
- opencode.json 설정 갱신
2026-05-27 12:58:08 +09:00

4.8 KiB
Raw Blame History

구조화된 자동화 표면

목표

외부 자동화가 OTO를 안정적으로 호출하고 결과를 해석할 수 있도록, 이미 존재하는 command catalog와 YAML validation 기반을 외부 소비 가능한 출력 계약으로 확장한다. 구조화된 실행 결과와 step event 계약을 함께 정리하고, oto exe --json의 최종 실행 결과를 외부 도구가 안정적으로 파싱할 수 있게 한다.

단계

CLI 자동화 표면 정리

상태

완료

구현 잠금

  • 상태: 해제
  • 이유: 완료된 Milestone이며 완료 기준과 완료 근거가 문서화되어 있다. 후속 확장은 별도 Milestone에서 다룬다.
  • 해제 근거: 완료된 Milestone으로 완료 근거가 작업 컨텍스트에 문서화되어 있다.
  • 잠금 중 금지:
    • 해당 없음

범위

  • Command.specs와 Command.catalogRows를 command catalog의 내부 단일 진실 소스로 유지한다.
  • 기존 YAML build/pipeline validation 흐름을 외부 자동화가 호출하고 해석할 수 있는 계약으로 정리한다.
  • 실행 결과와 step event를 외부 도구가 파싱하기 쉬운 형태로 구조화한다.
  • 기존 사람이 읽는 로그 출력과 자동화용 구조화 출력의 관계를 정리한다.

필수 기능

  • [catalog-cli] command catalog를 CLI 또는 다른 안정된 조회 경로로 노출하는 방식이 정의되어 있다. (oto catalog CLI 추가로 달성)
  • [yaml-validation] YAML validation의 입력, 출력, 실패 기준이 외부 자동화용 계약으로 정의되어 있다. (oto validate -f <file> --json, YamlValidationResult JSON 계약으로 달성)
  • [result-envelope] 실행 결과의 성공/실패, exit code, 에러 정보 표현이 출력 envelope로 구조화되어 있다. (BuildResult.toJson, CommandExe --json 출력 계약으로 달성)
  • [step-events] step event의 최소 필드와 발생 시점이 정의되어 있다. (StepEvent 모델, Pipeline.execute()의 started/completed/failed 기록, ExecutionContext 수집으로 달성)
  • [event-snapshot] executionResult.stepEvents가 build 완료 시점의 이벤트 히스토리를 안정적으로 보존한다. (Application.build()의 List<StepEvent>.of(context.stepEvents) 스냅샷 전달과 회귀 테스트로 달성)

완료 기준

  • 외부 자동화가 내부 Dart API에 직접 의존하지 않고 command catalog를 조회할 수 있다.
  • 외부 자동화가 실행 전에 파이프라인 구성을 검증하고 실패 원인을 해석할 수 있다. (schemaVersion, type, valid, phase, message, exitCode 출력으로 달성)
  • 외부 자동화가 실행 후 성공/실패와 실패 원인을 안정적으로 해석할 수 있다. (BuildResult.toJson 및 oto exe --json 출력으로 달성)
  • step 단위 진행 상황을 사람이 읽는 로그에만 의존하지 않고 소비할 수 있다. (BuildResult.toJson 내 stepEvents 배열 포함으로 달성)
  • 같은 프로세스에서 build가 연속 실행되어도 이전 BuildResult의 step event JSON이 다음 resetStepEvents()에 의해 비워지지 않는다. (BuildResult regression - stepEvents snapshot 테스트로 달성)

범위 제외

  • Edge agent 네트워크 프로토콜을 구현하지 않는다.
  • 웹 UI나 대시보드를 만들지 않는다.
  • 기존 YAML 커맨드 모델을 대체하지 않는다.

작업 컨텍스트

  • lib/oto/commands/command.dart, lib/oto/commands/command_registry.dart, lib/oto/core/build_result.dart, lib/oto/pipeline/**, assets/yaml/sample/**를 우선 확인한다.
  • 완료 근거는 Command.specs, Command.catalogRows, Application.validateYamlContent(), YamlValidationResult, StepEvent, ExecutionContext, Pipeline.execute(), BuildResult.toJson(), CommandExe --json이다.
  • command, pipeline, sample 도메인 rule이 관련될 수 있다.
  • 완료된 기준선:
    • Command.specs와 Command.catalogRows가 등록된 커맨드의 내부 catalog 소스로 존재한다.
    • Application.build()와 Pipeline.pipelineInitialize() 경로에 YAML build/pipeline validation 흐름이 존재한다.
    • Application.validateYamlContent()와 CommandValidateCli가 실행 없이 YAML을 검증하고 YamlValidationResult.toJson()으로 자동화용 결과를 출력한다.
    • BuildResult.toJson()은 schemaVersion, type: executionResult, success, exitCode, message, error, stepEvents를 포함한다.
    • Application.build()는 success/failure 결과 모두에 완료 시점의 stepEvents 스냅샷을 전달한다.
    • CommandExe --json은 사람이 읽는 실행 로그를 섞지 않고 parseable execution result JSON을 출력한다.
    • test/oto_application_test.dart, test/oto_core_test.dart, test/oto_context_test.dart가 result envelope, CLI JSON 출력, step event 수집과 스냅샷 보존을 검증한다.