---
{
  "schema": "proofline.requirement/v1",
  "id": "REQ-001",
  "title": "프로젝트 스캐폴드의 메시지 작성자 구분",
  "revision": "0.1",
  "status": "approved",
  "depends_on": [],
  "applies_to": ["chat-tui-message-rendering"],
  "language": "ko"
}
---

# REQ-001 — 프로젝트 스캐폴드의 메시지 작성자 구분

## 1. 목적

대화형 Textual TUI의 프로젝트 스캐폴드와 실행 기반을 보존하고, 메시지 작성자 의미를 명시적인 데이터 역할로 관리한다. 입력 정규화, 응답 선택, 메시지 누적 및 종료와 같은 대화 상호작용의 상세 규칙은 `REQ-002`에서 관리한다.

## 2. 배경

애플리케이션은 Python 3.11 이상과 Textual 런타임을 사용하는 로컬 TUI다. 기존 메시지 표시의 작성자 의미는 `ChatMessage`와 `MessageRole`로 표현되어야 하며, 화면 라벨과 구조적 스타일은 그 역할에서 파생되어야 한다. 이번 문서는 프로젝트 구조·패키징·실행 진입점과 승인된 작성자 모델을 보존하고, 대화 상호작용 규칙을 별도 요구사항으로 분리한다.

## 3. 범위

포함 범위는 Python 패키지 구조, 패키징 메타데이터, Textual 실행 기반, `chat_tui.app:main` 콘솔 실행 진입점과 승인된 메시지 작성자 모델이다. 작성자 모델은 `ChatMessage`와 `MessageRole`을 통해 사용자와 에이전트의 의미를 표현하고, 렌더러가 역할에서 라벨과 구조적 스타일을 파생할 수 있도록 한다.

제외 범위는 입력 정규화, 고정 응답 선택, 메시지 누적 순서, 빈 입력 처리, 입력창 초기화와 종료 단축키를 포함한 대화 상호작용의 세부 동작이다. 이러한 규칙과 인수 기준은 `REQ-002`에서 단일 정본으로 관리한다. 외부 API, LLM, 인증, 영속 저장소, 데이터베이스와 새 의존성도 추가하지 않는다.

## 4. 용어와 기준

프로젝트 스캐폴드는 Python 패키지 구조, 선언된 런타임 의존성과 콘솔 실행 진입점의 조합을 뜻한다. 메시지 역할은 작성자 의미를 나타내는 `user` 또는 `agent` 값이며, `ChatMessage.role`과 `ChatMessage.content`가 작성자 의미의 정본이다. 사용자·에이전트 라벨과 CSS 클래스는 이 역할에서 파생되는 표시 정보다.

## 5. 요구사항

### REQ-001.01 — 프로젝트 패키지와 실행 기반

프로젝트는 Python 3.11 이상에서 현재 Textual 의존성을 사용하고, 기존 패키지 구조와 `chat_tui.app:main` 콘솔 실행 진입점을 유지해야 한다. 구현은 외부 API, LLM, 인증, 영속 저장소 또는 별도 데이터베이스를 추가하지 않아야 한다.

### REQ-001.02 — 승인된 메시지 작성자 모델

메시지 모델은 `ChatMessage`와 `MessageRole`을 통해 작성자 역할과 본문을 함께 표현해야 한다. 역할 값은 `user`와 `agent`이며, UI 렌더러는 역할에서 사용자·에이전트 라벨과 기존 `user-message`·`response-message` 식별자를 파생해야 한다. 역할 구분은 색상에만 의존하지 않고 역할별 CSS 식별자와 테두리 또는 정렬 차이를 포함해야 한다.

## 6. 제약과 불변조건

- Python 3.11 이상과 현재 Textual 기반 TUI 구조 및 선언된 의존성을 유지한다.
- `chat_tui.app:main` 콘솔 실행 진입점과 기존 패키지 위치를 유지한다.
- 메시지의 작성자 의미는 CSS 클래스나 화면 색상에서 추론하지 않고 명시적인 `MessageRole` 값에서 확인한다.
- 사용자와 에이전트의 라벨 및 구조적 스타일은 역할과 일치해야 한다.
- 입력 처리와 응답 동작의 상세 규칙은 이 문서에 복제하지 않고 `REQ-002`를 따른다.
- 외부 API, LLM, 인증, 영속 저장소, 데이터베이스 및 새 의존성은 추가하지 않는다.

## 7. 인수 기준

### REQ-001.01-AC01 — 패키지와 실행 진입점 보존

프로젝트가 Python 3.11 이상과 선언된 Textual 의존성으로 설치되고 `chat_tui.app:main` 진입점을 계속 제공하면 통과로 판정한다. 이 기준은 프로젝트 구조와 실행 기반만 검증하며 대화 상호작용의 판정은 `REQ-002`에 위임한다.

### REQ-001.02-AC01 — 역할이 작성자 표시의 정본임

`ChatMessage`가 `MessageRole`과 본문을 함께 보유하고, 사용자와 에이전트 표시의 라벨·식별자·구조적 스타일이 그 역할에서 파생되며 색상만으로 역할을 판정하지 않으면 통과로 판정한다.

## 8. 오류 및 충돌 계약

- 프로젝트 설치 또는 콘솔 진입점이 제공되지 않으면 스캐폴드 요구사항을 충족한 것으로 판정하지 않는다.
- 정의되지 않은 메시지 역할은 정상 표시하지 않으며 역할과 라벨의 매핑은 명시적인 기준을 따른다.
- 프로젝트 구조·패키징·실행 기반에 관한 충돌은 이 문서를 따른다.
- 입력·응답·누적·입력창·종료 동작에 관한 충돌은 `REQ-002`를 따른다.

## 9. 데이터 및 인터페이스 계약

- `MessageRole`은 문자열 기반 열거형이며 값은 `user` 또는 `agent`다.
- `ChatMessage.role`은 필수 역할 값이고 `ChatMessage.content`는 필수 본문 문자열이다.
- 역할에서 사용자 라벨 `사용자` 또는 에이전트 라벨 `에이전트`를 파생할 수 있어야 한다.
- 사용자 표시 항목은 `chat-message user-message user-role` 식별자를, 에이전트 표시 항목은 `chat-message response-message agent-role` 식별자를 사용한다.
- 상세 입력·응답·세션 누적 계약은 `REQ-002`에 정의한다.

## 10. 하위 호환성

- Python 3.11 이상, 현재 Textual 런타임 의존성, 패키지 위치 및 `chat_tui.app:main` 진입점을 유지한다.
- 기존 `#conversation`과 `#user-input` 식별자를 유지한다.
- 작성자 모델과 역할별 표시를 추가해도 대화 영역 전체 레이아웃을 재설계하지 않는다.
- 입력 제출, 응답 선택, 입력창 초기화와 종료 동작은 `REQ-002`의 기존 계약을 따른다.

## 11. 검증 계획

패키지 메타데이터와 콘솔 진입점이 Python 3.11 이상 및 선언된 Textual 환경에서 제공되는지 확인한다. `ChatMessage`와 `MessageRole`의 역할-본문 모델, 역할별 라벨과 식별자, 테두리 또는 정렬 기반 스타일을 검증한다. 입력 정규화, 응답 선택, 메시지 순서, 빈 입력, 입력창 초기화와 종료 단축키의 실행 검증은 `REQ-002`의 테스트 추적성 계약에서 관리한다.

### 테스트 추적성 계약

테스트 정의:

```text
Test ID: TC-001-001
Verifies:
- REQ-001.01-AC01
- REQ-001.02-AC01
Test reference: 프로젝트 패키징 검사와 Textual 애플리케이션 테스트
Automated: 패키지 진입점, 메시지 역할 모델, 역할별 라벨·식별자·구조적 스타일을 자동 검증한다.
```

실행 증거:

```text
Test ID: TC-001-001
Requirement revision: REQ-001@0.1
Commit: 실행 증거 미기록
Environment: Python 3.11 이상, 선언된 Textual 런타임 의존성
Result: 미실행
Executed at: 검증 실행 시각 미기록
```

## 12. 추적성

근거 이슈는 Gitea 이슈 #6인 메시지 표시창의 메시지 작성자 구분 요청이다. 구현 PR은 아직 없으며, 관련 설계 문서는 데이터 모델, 인터페이스 계약, 런타임 흐름 및 프로젝트 구조 문서다. 이 문서는 프로젝트 스캐폴드와 승인된 작성자 모델의 정체성을 보존하고, 대화 상호작용의 상세 규칙은 `REQ-002`의 원본 Gitea 이슈 #8 추적성으로 분리한다.

## 13. 확정된 결정

프로젝트의 Python 패키지 구조, Textual 실행 기반과 `chat_tui.app:main` 진입점을 유지한다. 메시지 작성자 의미는 `MessageRole`과 `ChatMessage`에 명시적으로 보존하고 라벨·식별자·구조적 스타일은 역할에서 파생한다. 입력과 응답의 세부 동작은 `REQ-002`에서 관리한다.

## 14. 미결 사항

없음

## 15. 승인 기록

- 상태: `approved`
- 승인 주체: `spec-agent`
- 승인 근거: 승인 댓글 923 및 디스커버리 승인 결과

문서 분리와 정리만으로 기존 승인 상태, 승인 주체 또는 승인 근거를 변경하지 않는다.