Aggrega 파일 작성
Aggrega에서의 작성은 짧고 반복 가능한 루프입니다. 개발자의 Aggregate, 아키텍트의 Component, 운영 팀의 Recipe, 운영자의 Release 중 어떤 엔터티를 작성하든, 다음 다섯 단계를 거치면 빈 파일에서 검증된 파일에 이릅니다.
- 자신의 역할이 담당하는 엔터티를 고릅니다.
- JSON Schema와 레퍼런스 페이지에서 그 형태를 익힙니다.
- 빈 파일 대신 골격에서 시작합니다.
- 자신의 역할이 담당하는 필드를 채우고, 나머지는 각 담당자에게 맡깁니다.
- 검증한 다음 컴파일합니다.
이 페이지는 직접 손으로 작성하는 사람과 Model Context Protocol 서버를 통해 작성하는 AI 어시스턴트 모두를 위해 이 루프를 한 번 따라갑니다. 두 경로는 같은 레퍼런스 표면 위에서 도는 같은 루프입니다. 두 경로 모두 aggrega 바이너리가 필요하며, 바이너리 설치에서 명령 하나로 설치할 수 있습니다.
1. 자신의 역할이 담당하는 엔터티 고르기
Aggrega는 작성을 서로 협력하는 네 가지 역할, 즉 개발자 의도, 플랫폼 카탈로그, 인프라 레시피, 배포 연결로 나눕니다. 각 역할은 보통 특정 엔터티 종류의 집합을 담당합니다. 자신의 역할을 이미 알고 있다면 필요한 엔터티로 바로 이동하고, 그렇지 않다면 네 가지 역할은 페르소나를, 종류와 역할의 전체 대응표는 역할별 엔터티를 읽으십시오.
이 구분은 지침일 뿐 컴파일러가 강제하는 규칙이 아닙니다. 혼자 작성하는 사람은 모든 역할을 맡아 한 번에 모든 엔터티를 작성해도 됩니다. 컴파일러는 스키마 검증을 통과하는 어떤 작성 방식도 받아들입니다. 역할은 관심사를 명확히 하기 위해 존재할 뿐, 작성할 수 있는 것을 제한하기 위한 것이 아닙니다.
2. 형태 익히기
모든 엔터티 종류에는 정식 JSON Schema와 필드별 레퍼런스 페이지가 있습니다. 작성하기 전에 둘 다 읽으십시오.
- 스키마는 정확한 구조로, 필수 필드, 허용되는 값, 중첩을 정의합니다. 명령줄에서는
aggrega get-schema <kind>가 스키마를 출력하고,aggrega get-schema --list는 요청할 수 있는 모든 종류를 나열합니다. 어시스턴트는schema://<kind>리소스에서 같은 바이트를 읽습니다.aggrega get-schema레퍼런스를 참조하십시오. - 레퍼런스 페이지는 각 필드가 무엇을 의미하는지와 필드들이 서로 어떻게 관련되는지 설명합니다. 엔터티 페이지는
language-reference/entities/아래에 있습니다. 예를 들면 component나 aggregate입니다. 어시스턴트는langref://entities/<kind>리소스에서 같은 페이지를 읽습니다.
스키마는 구조적으로 무엇이 유효한지 알려 주고, 레퍼런스는 무엇이 합리적인지 알려 줍니다. 검증 시점의 거부를 피하려면 스키마를 읽고, 의도한 대로 동작하는 것을 작성하려면 레퍼런스를 읽으십시오.
3. 골격에서 시작하기
골격에서 시작하는 것이 빈 파일에서 시작하는 것보다 빠르고 오류도 적습니다. MCP 서버에 연결된 어시스턴트는 종류와 이름을 지정해 scaffold 도구를 호출하여, 해당 종류가 요구하는 모든 필드를 담고 아직 값이 필요한 곳마다 자리 표시자가 들어간 최소한의 시작점을 얻습니다. 손으로 작성할 때는 aggrega scaffold <kind> <name>이 같은 시작점을 표준 출력으로 출력하므로 이를 파일로 리디렉션하십시오. 또는 가장 가까운 작업 예제를 복사한 뒤 필요한 부분만 남기십시오.
어느 쪽이든 골격에는 필수 최상위 필드(apiVersion, kind, metadata.name)가 올바른 형태로 이미 들어 있으므로, 상용구가 아니라 자신의 역할이 담당하는 필드에 주의를 기울일 수 있습니다.
4. 자신의 역할이 담당하는 필드 채우기
자신의 역할이 책임지는 기둥만 채우고 나머지는 각 담당자에게 맡기십시오. 개발자는 애플리케이션 의도와 값을 제공하고, 아키텍트는 계약, 즉 개발자가 제공할 수 있는 값, component가 제공하는 출력, component가 노출하는 소켓을 선언합니다. 운영 팀은 개발자에게 보이는 표면을 바꾸지 않고 그 계약을 특정 provider에 매핑하며, 운영자는 배포를 연결합니다. 역할별 엔터티는 모든 종류에 대해 어떤 기둥이 어떤 역할에 속하는지 상세히 설명합니다.
각 값을 그 담당자가 관리하는 기둥에 두기 때문에, 개발자의 파일을 바꾸지 않고도 같은 개발자 의도가 환경마다 다른 인프라를 대상으로 할 수 있습니다. 작성 표면을 애초에 나누는 이유가 바로 이것입니다.
설명은 짧은 문단 몇 개로 유지하십시오. 엔터티의 metadata.description은 독자가 엔터티를 고르기 전에 읽는 글입니다. 이 설명은 엔터티와 함께 검색 가능한 설명으로 게시되며, aggrega search는 검색어를 이 설명과 대조합니다. 그 순간을 위해, 짧은 문단으로(접힌 description: > 블록에서는 빈 줄이 새 문단을 시작합니다) 엔터티가 무엇인지, 독자가 어떻게 사용하는지, 어디에서 실현되며 무엇을 하지 않는지를 작성하십시오. 독자가 엔터티를 고르기 전에 알아야 하는 제한도 간략하게 여기에 적습니다. 그 밖의 모든 내용, 즉 기본값이 왜 그러한지, 어떤 설정이 특정 대상에서 어떻게 동작하는지, 값이 각 실현 방식에서 무엇을 의미하는지는 해당 필드나 블록 옆의 YAML 주석에 적어, 그 필드를 다루는 사람이 읽을 수 있게 하십시오. 컴파일러는 설명의 길이를 제한하거나 그 내용에 따라 동작하지 않으므로, 설명을 짧게 유지하는 것은 독자를 위한 것입니다.
5. 검증한 다음 컴파일하기
파일에 의존하기 전에 확인하십시오.
- 어시스턴트는
validate도구를 호출합니다. 이 도구는 스키마 오류와 참조 오류를 그 자리에서 보고하므로, 어시스턴트는 초안을 돌려주기 전에 수정할 수 있습니다. - 손으로 작성할 때는
aggrega validate <file>이 하나의 Component, Feature, Recipe, FeatureRecipe, Workload 또는 Plugin 파일을 검사하고,aggrega validate --release <release>는 Release가 도달하는 모든 것을 그 Aggregate와 Manifest까지 포함해 검사합니다.aggrega lint는 카탈로그 엔터티에 게시 규율 규칙을 적용하고,aggrega inspect는 컴파일러가 보는 내용을 해석해 보여 줍니다. 전체 토폴로지가 준비되면aggrega pull --release <release>가 의존성을 해석하고 잠금 파일을 작성한 다음,aggrega build --release <release>가 Release를 경계별 아티팩트로 컴파일합니다. 빌드가 실패하면 무엇을 고쳐야 하는지 정확히 알려 줍니다.
일찍 검증하는 것이 나중에 빌드가 실패하는 것보다 비용이 적게 듭니다. 작성하고, 검증하고, 수정한 다음에야 컴파일하십시오.
AI 어시스턴트로 작성하기
aggrega mcp 명령은 MCP를 지원하는 모든 클라이언트를 Aggrega를 이해하는 작성 어시스턴트로 만들어 주는 Model Context Protocol 서버를 실행합니다. 연결되면 어시스턴트는 다음을 할 수 있습니다.
- 내장 작성 프롬프트를 통해 역할을 맡습니다. 프롬프트는 페르소나(개발자, 아키텍트, 운영)마다 하나씩 있고, 엔터티별 전용 템플릿도 있습니다. 각 프롬프트는 역할을 설정하고 어시스턴트가 스키마, 레퍼런스 페이지, 이 가이드를 참조하도록 하므로, 어시스턴트의 제안은 해당 역할이 담당하는 기둥 안에 머뭅니다.
- 리소스를 통해 레퍼런스를 읽습니다. 종류의 JSON Schema는
schema://<kind>, 모든 레퍼런스 페이지는langref://<path>, 이 가이드는authoring://<topic>에서 읽습니다. - 도구를 통해 작업 공간에서 작업합니다. 올바른 골격을 시작하는
scaffold, 초안을 확인하는validate, 카탈로그 엔터티를 살펴보는describe, 종류별로 스키마를 가져오는get-schema가 있습니다.
어시스턴트가 읽는 모든 내용은 사용자의 머신에서 제공됩니다. 스키마는 바이너리에 내장되어 있고, 가이드와 레퍼런스 페이지는 머신의 캐시에 보관된 문서 번들에서 제공되며, 서버는 시작할 때 캐시에 사본이 없으면 레지스트리에서 번들을 가져옵니다. 페이지 읽기, 스캐폴딩, 검증은 네트워크에 접속하지 않습니다. 번들을 가져올 수 없는 경우 스키마는 계속 제공되지만 페이지는 제공되지 않습니다. 클라이언트를 연결하려면 MCP 서버 연결을 따르십시오. 어시스턴트가 사용할 수 있는 나머지는 어시스턴트가 Aggrega로 할 수 있는 일에서 다룹니다. 명령 자체에 대해서는 aggrega mcp 레퍼런스를 참조하십시오.