본문으로 건너뛰기

에이전트 기반 워크플로

Neat 프레임워크의 공개 API는 단순히 개발자가 직접 코드를 작성하는 데 사용되는 것뿐만 아니라, 개발자를 대신하여 Modalix를 대상으로 하는 코드를 작성하는 AI 코딩 에이전트용으로 설계되었습니다. 이 페이지에서는 프레임워크의 여러 디자인 선택이 현재와 같은 형태로 나타나는 이유를 설명합니다. 즉, 이러한 선택은 단순히 개발자를 위한 것이 아니라, API를 사용하는 에이전트에게 최적화되어 있습니다.

에이전트가 프레임워크로부터 필요로 하는 것​

익숙하지 않은 API를 기반으로 코드를 생성하는 AI 에이전트는 일반적으로 다음이 필요합니다.

  1. 작은 규모의 공공 공간 — 종류가 적으면 익혀야 할 내용도 줄어듭니다.
  2. 자체 설명형 타입 — 타입 시그니처는 계약 내용을 암시하는 것뿐만 아니라, 계약 내용을 명확하게 포함해야 합니다.
  3. 각 작업을 수행하는 한 가지 방법 — 여러 가지 동등한 방법이 있는데, 바로 이러한 선택지에서 에이전트가 실수를 하는 것입니다.
  4. 인접 문서 — 에이전트는 8000줄짜리 설계 문서가 아닌 @brief 블록을 읽습니다. 중요한 정보는 반드시 해당 기호와 함께 있어야 합니다.
  5. 결정론적 출력 — 에이전트가 테스트 스냅샷을 작성할 때, 바이트 단위의 결정론적 방식은 스냅샷의 안정성을 보장합니다.
  6. 근본 원인을 명시하는 오류 — 어떤 문제가 발생했을 때, 오류 메시지는 단순히 "그래프 빌드 실패"라고 표시하는 대신, 어떤 커널/계약/옵션이 잘못되었는지 구체적으로 알려주어야 합니다.
  7. 재현 관련 아티팩트 — 에이전트의 코드가 실패할 경우, 디버거에 repro_gst_launch 문자열을 붙여넣고 에이전트를 다시 실행하지 않고도 반복할 수 있습니다.
  8. 숨겨진 전역 변수는 사용하지 않음 — 모든 동작은 생성자 인자 또는 Node 옵션으로 정의되어야 하며, 런타임에 읽히는 환경 변수로 정의되어서는 안 됩니다.
  9. 안정적인 식별자 — 동일한 노드 + 동일한 옵션 → 동일한 요소 이름 → 동일한 실행 문자열 → 안정적인 테스트 환경.
  10. 모델 아카이브를 코드 대신 데이터로 사용 — 모델은 프레임워크가 로드하는 일련의 파일이고, 에이전트가 컴파일해야 하는 헤더 파일이 아닙니다.
  11. 조립 가능한 구성 요소 — 노드, 모델, 재사용 가능한 그래프 조각들이 서로 연결되어 작동합니다. 에이전트는 프레임워크가 어떤 조합을 "지원"하는지 알 필요가 없습니다. 왜냐하면 플래너가 빌드 시점에 그에 대한 답을 제공하기 때문입니다.
  12. 빌드 시점에 발생하는 명확한 검증 오류 — 오류는 첫 번째 pull() 시점이 아닌 Graph::build() 과정에서 발생합니다. 에이전트의 반복 루프는 오류가 정확한 줄에서 발생했음을 나타내야 합니다.
  13. 구조화된 GraphReport — 빌드 프로세스에서 수행된 작업에 대한 프로그래밍 방식의 접근을 제공하여, 에이전트가 자신의 작업을 검증할 수 있도록 합니다.
  14. 점진적 정보 공개 — Model은 가장 간단한 방법이고, Graph::add()는 그 다음 단계이며, 사용자 지정 노드는 더 복잡한 방법입니다. 에이전트는 먼저 가장 간단한 방법을 사용합니다.
  15. 버전이 지정된 MPK 계약 — 모델 아카이브에는 충분한 메타데이터가 포함되어 있어, 이를 기반으로 코드를 생성하는 에이전트가 외부 문서를 참조할 필요가 없습니다.

이러한 요소들은 프레임워크 전반에 걸쳐 구체적인 디자인 결정 사항으로 나타납니다.

  • 작은 공개 표면(모델, 텐서, 샘플, 노드, 그래프, 실행)은 에이전트가 애플리케이션 코드를 학습하는 데 필요한 전부입니다.
  • Graph::describe()는 구조화된 계획 요약을 반환하며, 이를 통해 에이전트는 자신의 파이프라인을 확인할 수 있습니다.
  • NeatError에는 error_code()와 GraphReport가 포함되어 있으며, 에이전트는 코드를 활성화할 수 있습니다.
  • Node::backend_fragment()는 결정론적입니다. 즉, 에이전트는 파이프라인에 대해 골든 스트링 테스트를 작성할 수 있습니다.
  • MpkContract는 모델에 대한 유일하고 권위 있는 설명입니다. 모델을 기반으로 배선 코드를 생성하는 에이전트는 이 외에 다른 것이 필요하지 않습니다.

애플리케이션 개발자가 얻는 이점​

에이전트가 아니더라도 에이전트 친화적인 API 디자인의 이점을 누릴 수 있습니다. 자동화된 코드 생성의 신뢰성을 높이는 요소들이 수동 코드 검토를 더 쉽게 하고, 리팩터링을 더 안전하게 하며, AI 기반 개발(Claude Code, Copilot, Cursor)을 Modalix 코드에서 더욱 효율적으로 만들어 줍니다.

더 읽어보기​

  • “Neat을 소개합니다” — 디자인 심층 분석의 제0.1절.
  • Graph::describe() — 프로그램별 계획 요약.
  • NeatError — 구조화된 오류 유형입니다.
  • Model — 모델 아카이브를 로드하고 MPK 계약을 분석했습니다.