AI 에이전트로 개발하기
화면을 만드는 일은 규격을 지키는 일입니다. 버튼의 높이, 표의 구분선, 다크 테마의 색상, 비어 있을 때 보여줄 문장까지 제품 전체에서 일관되어야 하며, 이 규격은 사람이 외우기에는 많고 지키기에는 반복적입니다.
로그프레소 디자인 시스템은 이 규격을 AI 에이전트가 직접 읽을 수 있는 형태로 제공합니다. 에이전트에게 화면을 만들도록 지시할 때 참조할 자료의 위치와 읽는 순서를 알려주면, 에이전트가 규격을 조회하며 화면을 구현할 수 있습니다.
이 문서는 에이전트를 사용하지 않는 경우에도 유용합니다. 디자인 시스템 자료가 어디에 있고 무엇을 지켜야 하는지 정리한 문서이기 때문입니다.
디자인 시스템 참조 자료
로그프레소 디자인 시스템은 다음 자료를 제공합니다. 에이전트에게는 개별 문서 대신 매니페스트 주소를 먼저 알려주는 것이 좋습니다. 매니페스트가 나머지 자료의 목록을 담고 있습니다.
| 용도 | 주소 |
|---|---|
| 매니페스트(시작점) | https://design.logpresso.com/design-system.manifest.json |
| 에이전트 가이드 | https://design.logpresso.com/docs/AI-AGENT-GUIDE.md |
| 시작 프롬프트 | https://design.logpresso.com/agent-starters.json |
| 컴포넌트 목록 | https://design.logpresso.com/docs/components/components.md |
| 화면 패턴 목록 | https://design.logpresso.com/docs/patterns/patterns.md |
| 색상 토큰 정본 | https://design.logpresso.com/sonar5.css |
| 디자인 토큰 정의 | https://design.logpresso.com/docs/tokens/design-tokens.json |
| 접근성 기준 | https://design.logpresso.com/docs/accessibility/component-accessibility-matrix.json |
색상 값은 sonar5.css를 기준으로 합니다. 이 파일이 로그프레소 소나 웹 콘솔이 사용하는 변수를 정의하고 있으며, 앱은 같은 이름과 값을 사용합니다. design-tokens.json은 변수 이름 체계가 다르므로 타이포와 간격 규격, 토큰의 분류를 확인하는 데 사용합니다. 자세한 구분은 디자인 시스템 준수에서 설명합니다.
디자인 시스템은 설치해서 가져다 쓰는 컴포넌트 라이브러리를 제공하지 않습니다. 위 자료를 읽고 토큰과 컴포넌트 규격을 앱의 스타일 파일로 옮겨 구현하는 방식입니다.
읽기 순서
디자인 시스템은 문서를 읽는 순서를 규정합니다. 상위 문서가 화면의 구조를 정하고 하위 문서가 개별 컴포넌트의 세부 규격을 정하므로, 순서를 건너뛰면 상위 규칙을 놓치게 됩니다.
매니페스트 → 에이전트 가이드 → 화면 패턴 → 상위 조합 → 하위 컴포넌트 → 기초 문서
이 순서에는 원칙이 하나 있습니다. 상위 조합은 화면의 구조를 소유하고, 하위 컴포넌트는 자기 규격을 소유합니다. 상위 문서가 하위 컴포넌트의 규격을 임의로 바꾸어서는 안 됩니다. 예를 들어 화면 배치를 정의하는 문서가 버튼의 높이를 다시 정의하는 일은 허용되지 않습니다.
반드시 지킬 것
모든 화면은 여섯 가지 상태를 다뤄야 합니다. 데이터가 채워진 화면만 만들고 끝내는 것이 가장 흔한 누락입니다.
| 상태 | 설명 |
|---|---|
| 기본 | 데이터가 정상적으로 표시된 상태 |
| 로딩 | 데이터를 불러오는 중 |
| 비어 있음 | 표시할 데이터가 없음 |
| 오류 | 조회에 실패함, 다시 시도할 수단을 함께 제공 |
| 권한 | 권한이 없어 조회하거나 조작할 수 없음 |
| 선택 | 목록에서 현재 선택된 항목 |
비어 있는 상태는 원인에 따라 문장을 구분해야 합니다. 검색 조건 때문에 결과가 없는 것과 애초에 데이터가 없는 것은 사용자가 취할 다음 행동이 다릅니다. 두 경우에 같은 문장을 보여주면 사용자는 자기가 무엇을 해야 하는지 알 수 없습니다.
추측해서 채우지 말아야 하는 것들이 있습니다. 에이전트는 빈칸을 그럴듯한 내용으로 채우는 경향이 있으므로 명시적으로 금지해야 합니다.
- 디자인 토큰 값: 문서에 없는 색상이나 간격 값을 만들어내지 않습니다.
- 컴포넌트 규격: 문서화되지 않은 상태나 변형을 임의로 정의하지 않습니다.
- 제품 문구, 업무 규칙, 권한 정책, API 동작: 확인되지 않은 것은 확인되지 않았다고 표시합니다.
색상만으로 정보를 전달하지 않습니다. 상태, 심각도, 선택 여부는 색상 외에 텍스트나 아이콘, 접근성 속성으로도 구분할 수 있어야 합니다. 키보드 포커스 표시를 제거하는 것도 금지됩니다.
실제 고객 데이터를 예시로 쓰지 않습니다. 계정, IP 주소, 호스트 이름, 자격 증명은 예시에도 실제 값을 넣지 않습니다. 예시 IP 주소는 RFC 5737이 정한 범위(192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24)를 사용합니다.
화면 패턴
디자인 시스템은 자주 쓰이는 화면 구조를 패턴으로 정리해 두었습니다. 화면을 새로 만들 때는 가장 가까운 패턴을 먼저 고르고, 그 패턴 문서가 지정하는 문서를 순서대로 읽습니다.
| 구분 | 패턴 |
|---|---|
| 화면 구조 | 대시보드, 목록-상세, 설정·정책 양식, 데이터 표 워크플로, 감사·이벤트 이력, 단계별 안내 설정 |
| 상호작용 | 일괄 작업, 파괴적 작업, 로딩 피드백, 낙관적 갱신, 양식 제출, 인라인 편집, 계층 탐색, 빈 상태 복구, 권한별 UI |
각 패턴에는 에이전트에게 그대로 전달할 수 있는 시작 프롬프트가 준비되어 있습니다. 위 표의 agent-starters.json 주소에서 확인할 수 있으며, 목록은 갱신될 수 있으므로 실제 값은 사이트에서 확인하시기 바랍니다.
에이전트 지침 파일
앱 저장소 루트에 AGENTS.md 파일을 두면 에이전트가 작업을 시작할 때 이 파일을 읽습니다. 대화마다 같은 규칙을 반복해서 알려주지 않아도 되므로, 빌드 규약처럼 변하지 않는 내용은 이 파일에 적어 둡니다.
AGENTS.md에는 다음 내용을 담습니다.
| 항목 | 내용 |
|---|---|
| 앱 고유 값 | 앱 코드, 번들 이름, 자바 패키지, 접속 프로파일 유형, REST 주소 접두사 |
| 디렉터리 구성 | 어떤 디렉터리에 무엇이 들어가는지 |
| 빌드 규약 | 빌드 단계와 순서, 버전을 고정해야 하는 플러그인과 그 이유 |
| 매니페스트 규칙 | 앱 코드 형식, 메뉴 이동 경로 형식, 필수 파일 |
| 화면 동작 규약 | 빌드 기준 경로, 화면 이동 메시지, 테마 연동 |
| REST API 규약 | 주소 규칙, 세션 전달 방식 |
| 디자인 시스템 | 참조 주소와 읽기 순서, 자주 틀리는 규격 |
| 금지 사항 | 하지 말아야 할 것의 목록 |
| 검증 방법 | 무엇을 실행하고 무엇을 확인하면 되는지 |
앱 고유 값은 표로 정리해 파일 앞쪽에 두는 것이 좋습니다. 다른 앱에 이 파일을 재사용할 때 이 표만 고치면 되기 때문입니다.
| | |
| --- | --- |
| App code | `sample` |
| Bundle symbolic name | `com.logpresso.sonar.sample` |
| Java package | `com.logpresso.sonar.sample` |
| Connect profile type | `sample` |
| REST endpoint prefix | `/sonar/sample` (browser: `/api/sonar/sample`) |
| UI dev port | 6100 |
작성된 예는 앱 예제 저장소의 AGENTS.md에서 확인할 수 있습니다. 자기 앱 저장소로 복사한 뒤 앱 고유 값만 바꾸어 사용하시기 바랍니다.
Claude Code는 CLAUDE.md 파일도 함께 읽습니다. 두 파일에 같은 내용을 넣으면 한쪽만 갱신되어 서로 어긋나기 쉬우므로, CLAUDE.md에는 다음 한 줄만 두는 것을 권장합니다.
See [AGENTS.md](AGENTS.md) for build, runtime, and design-system contracts.
단계별 프롬프트
이 챕터의 각 문서 마지막에는 해당 단계를 에이전트에게 맡길 때 사용할 프롬프트가 있습니다.
| 단계 | 프롬프트 위치 |
|---|---|
| UI 프로젝트 생성 | UI 프로젝트 생성 |
| 빌드 문제 해결 | UI 빌드와 설치 |
| 메뉴 등록 | 앱 매니페스트와 메뉴 |
| 화면 이동 구현 | 화면 라우팅 |
| 서버 데이터 연결 | REST API 플러그인 |
| 디자인 규격 검수 | 디자인 시스템 준수 |
에이전트가 만든 화면은 반드시 실제 로그프레소 소나에 설치해서 확인해야 합니다. 빌드가 통과하고 코드가 그럴듯해 보이는 것과 화면이 제대로 동작하는 것은 별개입니다. 특히 다크 테마 전환, 브라우저 뒤로 가기, 데이터가 없는 상태는 실행해 보지 않으면 확인할 수 없습니다.
다음 절에서는 앱에 UI 프로젝트를 추가하는 방법을 설명합니다.