8.2 KiB
schema, id, title, revision, status, depends_on, applies_to, language
| schema | id | title | revision | status | depends_on | applies_to | language | |
|---|---|---|---|---|---|---|---|---|
| proofline.requirement/v1 | REQ-001 | 프로젝트 스캐폴드의 메시지 작성자 구분 | 0.1 | approved |
|
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의 테스트 추적성 계약에서 관리한다.
테스트 추적성 계약
테스트 정의:
Test ID: TC-001-001
Verifies:
- REQ-001.01-AC01
- REQ-001.02-AC01
Test reference: 프로젝트 패키징 검사와 Textual 애플리케이션 테스트
Automated: 패키지 진입점, 메시지 역할 모델, 역할별 라벨·식별자·구조적 스타일을 자동 검증한다.
실행 증거:
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 및 디스커버리 승인 결과
문서 분리와 정리만으로 기존 승인 상태, 승인 주체 또는 승인 근거를 변경하지 않는다.