gitea-agent-testbed/docs/requirements/req-001_project-scaffold.md

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		프로젝트 스캐폴드 Python 패키징 콘솔 실행 진입점	ko

REQ-001 — 프로젝트 스캐폴드와 실행 진입점

1. 목적

이 요구사항은 Python 3.11 이상에서 실행되는 Textual 기반 대화형 TUI 프로젝트의 스캐폴드, 패키징 메타데이터와 실행 진입점을 정의한다. 프로젝트가 표준 Python 패키지로 설치되고 지정된 콘솔 명령 또는 모듈 실행 방식으로 시작되는 상태를 보장한다. 대화 입력 처리와 응답 표시 동작은 별도 요구사항에서 관리하며 이 문서에서는 정본으로 정의하지 않는다.

기존 프로젝트 스캐폴드 요구사항의 정체성과 승인 이력은 유지한다. 기존 승인 상태와 승인 근거를 임의로 초안 상태로 되돌리거나 삭제하지 않으며, 이번 문서 정리는 프로젝트 스캐폴드와 실행 기반의 범위만 명확히 하는 변경으로 한정한다.

2. 배경

프로젝트는 소스 코드를 src 레이아웃 아래에 두고 chat_tui 패키지로 제공한다. 패키징은 setuptools 빌드 백엔드를 사용하며 Python 3.11 이상을 실행 환경으로 요구한다. 런타임에는 Textual 0.47 이상 1.0 미만을 사용하고, 테스트용 선택 의존성으로 pytest 8.0 이상을 제공한다. 패키지 버전은 현재 0.1.0으로 관리한다.

패키지 설치와 실행 진입점은 대화 기능과 독립적으로 검증할 수 있는 프로젝트 기반 계약이다. 대화 입력 정규화, 메시지 누적, 고정 응답 선택과 표시, 빈 입력 처리, 입력창 초기화 및 종료 동작은 원본 이슈인 Gitea 이슈 #8의 재작업 범위에 따라 별도 대화 요구사항 문서에서 추적한다.

3. 범위

이 문서는 src/chat_tui Python 패키지의 기본 구조, 패키지 버전 공개, pyproject.toml의 빌드 시스템과 프로젝트 메타데이터, Python 및 런타임 의존성, 테스트 선택 의존성, chat-tui 콘솔 스크립트와 python -m chat_tui 모듈 실행 진입점을 포함한다. 소스 디렉터리를 패키지 탐색 대상으로 사용하는 설치 구조도 포함한다.

대화 입력 정규화, 메시지 누적, 고정 응답 선택 및 표시, 역할별 대화 표시, 빈 입력 처리, 입력창 초기화와 종료 단축키의 상세 동작 및 수용 기준은 포함하지 않는다. 해당 내용은 별도 대화 상호작용 요구사항에서 단일 정본으로 관리한다. 외부 API, LLM, 네트워크 서비스, 데이터베이스, 영속 저장소, 새 의존성, 배포 방식 또는 실행 환경 변경도 포함하지 않는다.

포함

Python 3.11 이상을 대상으로 하는 chat_tui 패키지의 프로젝트 구조, setuptools 패키징 설정, 런타임 의존성, 테스트 선택 의존성, 콘솔 스크립트 진입점과 python -m 실행 진입점을 다룬다.

제외

사용자 입력 정규화, 대화 메시지 누적, 고정 응답 선택 및 표시, 빈 입력 처리, 입력창 초기화, 종료 단축키를 포함한 대화 상호작용 동작은 다루지 않는다. 외부 API 연동, 영속성, 배포 환경 변경과 새 의존성 추가도 포함하지 않는다.

4. 용어와 기준

스캐폴드는 다음 기준을 따른다.

• 프로젝트 이름은 gitea-agent-testbed이고 Python 패키지 이름은 chat_tui이다.
• 소스 루트는 src이며 패키지 탐색 설정은 해당 루트를 기준으로 한다.
• 패키지 초기화 모듈은 패키지 버전 0.1.0을 공개한다.
• 모듈 실행 진입점은 애플리케이션 모듈의 공개 실행 함수를 호출한다.
• 콘솔 스크립트 진입점은 chat_tui.app:main으로 연결한다.
• 빌드 백엔드는 setuptools를 사용하고 빌드 요구 버전은 68 이상이다.
• 테스트 설정은 src를 Python 경로에 포함하고 tests 디렉터리를 검색 대상으로 한다.
• 프로젝트 스캐폴드 설명은 실제 패키지 구조와 패키징 설정에 부합해야 한다.
• 대화 상호작용의 의미와 세부 검증 기준은 이 문서가 아니라 분리된 대화 요구사항을 기준으로 한다.

5. 요구사항

시스템은 다음 프로젝트 기반 요구를 충족해야 한다.

• 프로젝트는 Python 3.11 이상에서 설치 및 실행 가능한 표준 Python 패키지 구조를 제공해야 한다.
• 빌드 설정은 setuptools를 사용하고 src 아래의 chat_tui 패키지를 배포 대상에 포함해야 한다.
• 프로젝트 메타데이터에는 프로젝트 이름, 현재 버전, 설명, README 참조, Python 최소 버전과 Textual 런타임 의존성이 포함되어야 한다.
• 테스트 선택 의존성을 별도로 설치할 수 있어야 하며 pytest 8.0 이상을 지정해야 한다.
• chat-tui 명령을 실행하면 chat_tui.app 모듈의 main 함수가 호출되어 애플리케이션 시작 절차로 진입해야 한다.
• python -m chat_tui를 실행하면 콘솔 명령과 동일한 애플리케이션 시작 함수를 호출해야 한다.
• 패키지 버전은 초기 스캐폴드 기준인 0.1.0을 일관되게 노출해야 한다.
• 패키징 및 실행 진입점 검증은 대화 기능의 상세 동작과 독립적으로 수행할 수 있어야 한다.

Python 패키지 구조와 메타데이터

프로젝트는 소스 디렉터리 기반의 chat_tui Python 패키지로 구성되어야 하며, 패키징 메타데이터에 프로젝트 이름, 버전, 설명, Python 3.11 이상 실행 조건과 Textual 런타임 의존성을 선언해야 한다. 패키지는 setuptools 빌드 백엔드와 소스 디렉터리 검색 설정을 사용해야 하며, 패키지 버전은 애플리케이션에서 조회할 수 있어야 한다.

영향 범위는 Python 패키지 설치와 import 경계, 개발자와 패키지 설치 도구 및 실행 진입점에 한정된다. 영속성 변경과 마이그레이션은 없으며, Python 3.11 이상과 기존 패키지 이름을 유지한다. setuptools 기반 editable 설치가 가능해야 한다.

모듈 실행 진입점

프로젝트는 python -m chat_tui 명령으로 실행할 수 있어야 한다. 모듈 실행은 애플리케이션의 공개 실행 함수를 호출해야 하며, 패키지를 단순히 import하는 것만으로 애플리케이션을 시작해서는 안 된다.

영향 범위는 모듈 실행 계약과 Python 모듈 실행 환경에 한정된다. 영속성 변경과 마이그레이션은 없으며, 기존 모듈 실행 방식과 공개 실행 함수 연결을 유지한다. 패키지가 Python 모듈 검색 경로에 설치되어 있어야 한다.

콘솔 스크립트 실행 진입점

패키징 설정은 chat-tui 콘솔 명령을 애플리케이션 모듈의 공개 실행 함수에 연결해야 한다. 설치 후 사용자는 별도의 경로 지정이나 내부 모듈 호출 없이 해당 명령으로 TUI를 시작할 수 있어야 한다.

영향 범위는 설치 후 제공되는 콘솔 명령과 최종 사용자 및 운영 스크립트에 한정된다. 영속성 변경과 마이그레이션은 없으며, 프로젝트에서 정의한 콘솔 명령 이름과 실행 함수 연결을 유지한다. 패키지 설치 시 console script가 생성되어야 한다.

대화 입력, 응답, 메시지 표시와 종료 동작의 상세 요구사항 및 수용 기준은 이 문서에 중복해서 정의하지 않고 분리된 대화 요구사항에서 관리한다.

REQ-001.01 — Python 패키지 구조와 메타데이터를 제공한다

프로젝트는 Python 3.11 이상에서 설치 및 실행 가능한 표준 Python 패키지 구조를 제공해야 한다. 소스 루트는 src이며 src/chat_tui 패키지를 배포 대상으로 포함해야 한다. setuptools 빌드 백엔드와 소스 디렉터리 패키지 검색 설정을 사용하고, 프로젝트 이름, 버전 0.1.0, 설명, README 참조, Python 최소 버전 및 Textual 0.47 이상 1.0 미만의 런타임 의존성을 패키징 메타데이터에 선언해야 한다. 테스트용 pytest 8.0 이상 의존성은 선택적으로 설치할 수 있어야 하며, 패키지 버전은 애플리케이션에서 조회할 수 있고 프로젝트 메타데이터와 일치해야 한다.

영향 범위

인터페이스: Python 패키지 설치와 import 경계에 영향을 준다. 영속성: 영향 없음. 후속 사용 주체: 개발자, 패키지 설치 도구와 실행 진입점. 마이그레이션: 필요 없음. 호환성: Python 3.11 이상, 프로젝트 이름, 패키지 이름과 버전 계약을 유지한다. 배포 전제 조건: setuptools 기반 설치와 src 패키지 탐색이 가능해야 한다.

REQ-001.02 — 모듈 실행 진입점을 제공한다

프로젝트는 python -m chat_tui 명령으로 실행할 수 있어야 한다. 모듈 진입점은 애플리케이션의 공개 실행 함수인 main을 호출해야 하며, 패키지를 단순히 import하는 것만으로 애플리케이션을 시작해서는 안 된다. 실행 진입점은 설치된 패키지와 선언된 런타임 환경에서 동일한 애플리케이션 시작 흐름으로 연결되어야 한다.

영향 범위

인터페이스: python -m chat_tui 실행 계약에 영향을 준다. 영속성: 영향 없음. 후속 사용 주체: 개발자와 운영자가 사용하는 Python 모듈 실행 환경. 마이그레이션: 필요 없음. 호환성: 기존 모듈 실행 방식과 공개 실행 함수 연결을 유지한다. 배포 전제 조건: 패키지가 Python 모듈 검색 경로에 설치되어 있어야 한다.

REQ-001.03 — 콘솔 스크립트 실행 진입점을 제공한다

패키징 설정은 chat-tui 콘솔 명령을 chat_tui.app:main에 연결해야 한다. 설치 후 사용자는 별도의 경로 지정이나 내부 모듈 호출 없이 해당 명령으로 TUI를 시작할 수 있어야 하며, 콘솔 명령과 모듈 실행 명령은 동일한 애플리케이션 시작 동작을 호출해야 한다.

영향 범위

인터페이스: 설치 후 제공되는 chat-tui 콘솔 명령에 영향을 준다. 영속성: 영향 없음. 후속 사용 주체: 최종 사용자와 운영 스크립트. 마이그레이션: 필요 없음. 호환성: 프로젝트에서 정의한 콘솔 명령 이름과 실행 함수 연결을 유지한다. 배포 전제 조건: 패키지 설치 시 console script가 생성되어야 한다.

6. 제약과 불변조건

• 프로젝트는 Python 3.11 이상에서 실행되어야 한다.
• 패키지 구성은 src 기반 레이아웃을 유지하고 애플리케이션 패키지와 테스트 패키지의 책임을 분리해야 한다.
• 런타임 의존성은 호환되는 Textual 범위에서 관리하고 테스트 의존성은 선택적 설치 항목으로 제공해야 한다.
• 패키징 메타데이터, 공개 버전, 설명 및 지원 Python 버전은 서로 일관되어야 한다.
• 콘솔 실행 진입점과 모듈 실행 진입점은 동일한 애플리케이션 시작 함수를 호출해야 한다.
• 이 문서는 프로젝트 구조, 패키징 및 실행 진입점만 정본으로 관리하며 대화 상호작용의 상세 규칙과 인수 기준은 별도 요구사항 문서에서 관리한다.
• 외부 API, LLM, 데이터베이스, 영속 저장소 또는 추가 배포 환경을 도입하지 않는다.
• 기존 프로젝트 구조와 실행 계약을 사용하는 호출자는 별도 변환 없이 계속 사용할 수 있어야 한다.

7. 인수 기준

• Python 3.11 이상 환경에서 프로젝트를 설치하면 src 아래의 패키지와 선언된 런타임 의존성이 정상적으로 구성되어야 한다.
• 패키징 설정에 프로젝트 이름, 버전, 설명, README 참조, Python 최소 버전, Textual 의존성 및 소스 디렉터리 검색 설정이 포함되어야 한다.
• 테스트 선택 의존성을 별도로 설치할 수 있고 저장소의 테스트를 검색하여 실행할 수 있어야 한다.
• 설치된 chat-tui 명령은 애플리케이션의 공개 시작 함수를 호출해야 한다.
• python -m chat_tui 실행도 동일한 공개 시작 함수를 통해 애플리케이션을 시작해야 한다.
• 패키지에서 조회되는 공개 버전과 패키징 메타데이터의 버전은 일치해야 한다.
• 모듈을 단순히 import하는 것만으로 애플리케이션이 시작되어서는 안 된다.
• 패키징 설정에 명시되지 않은 외부 연동이나 추가 실행 전제 조건이 없어야 한다.
• 대화 입력과 응답 동작의 기존 회귀 검증은 별도 요구사항 문서의 범위에서 계속 확인되어야 하며, 이 문서에서는 해당 기준을 반복하지 않는다.
• 검증은 지원되는 Python 환경에서 패키지 설치, 공개 버전 조회, 모듈 실행 경로, 콘솔 실행 경로 및 테스트 검색 결과를 확인하는 방식으로 수행한다.

REQ-001.01-AC01 — 패키징 메타데이터가 프로젝트 계약과 일치한다

판정 기준

프로젝트 이름, 버전, 설명, README 참조, Python 3.11 이상 조건, Textual 런타임 의존성, pytest 선택 의존성 및 src 기반 패키지 검색 설정이 모두 선언되어 있으면 통과로 판정한다.

검증

pyproject.toml을 확인하고 Python 3.11 이상 환경에서 테스트 선택 사항을 포함한 설치를 수행하여 패키지와 선언된 의존성이 정상적으로 구성되는지 검증한다.

검증 분류

수준: integration; 백엔드: Python 패키징 도구와 setuptools; 케이스: positive

상태 불변조건

성공 시 선언된 패키지와 의존성이 설치되어야 한다. 패키징 설정에 명시되지 않은 외부 연동이나 배포 설정은 추가되지 않아야 한다. 설치 실패 시 유효하지 않은 패키지 계약을 성공으로 간주하지 않아야 한다.

REQ-001.01-AC02 — 패키지 버전을 조회할 수 있다

판정 기준

chat_tui 패키지를 import했을 때 비어 있지 않은 버전 값이 제공되고 패키징 메타데이터의 0.1.0과 일치하면 통과로 판정한다.

검증

Python에서 chat_tui.__version__을 조회하고 프로젝트 메타데이터의 버전 선언과 비교한다.

검증 분류

수준: unit; 백엔드: Python import 시스템; 케이스: positive

상태 불변조건

성공 시 패키지 import와 버전 조회가 가능해야 한다. 버전 조회가 패키지 초기화 중 외부 상태를 변경해서는 안 된다. 조회 실패 시 패키지 계약을 충족한 것으로 판정하지 않는다.

REQ-001.02-AC01 — 모듈 명령이 애플리케이션을 시작한다

판정 기준

설치된 패키지 환경에서 python -m chat_tui를 실행했을 때 공개 실행 함수를 통해 TUI가 시작되면 통과로 판정한다.

검증

모듈 진입점이 애플리케이션의 공개 실행 함수를 직접 실행 조건에서 호출하는지 확인하고, 격리된 실행 환경에서 모듈 명령을 시작하여 초기 화면이 생성되는지 검증한다.

검증 분류

수준: end-to-end; 백엔드: Python 모듈 실행기와 Textual 런타임; 케이스: positive

상태 불변조건

성공 시 모듈 실행은 공개 실행 함수를 통해 애플리케이션을 시작해야 한다. 모듈을 import하는 것만으로 TUI가 시작되어서는 안 된다. 초기화 실패를 정상 시작으로 기록하지 않는다.

REQ-001.03-AC01 — 설치 후 콘솔 명령이 생성되고 실행된다

판정 기준

설치가 완료된 환경에서 chat-tui 명령이 실행 경로에 생성되고 애플리케이션을 시작하면 통과로 판정한다.

검증

패키지를 설치한 뒤 chat-tui 명령의 생성 여부와 연결된 실행 대상을 확인하고 명령을 실행하여 Textual 애플리케이션의 초기 상태가 표시되는지 검증한다.

검증 분류

수준: end-to-end; 백엔드: setuptools console script와 Textual 런타임; 케이스: positive

상태 불변조건

성공 시 콘솔 명령은 지정된 공개 실행 함수를 호출해야 한다. 명령 생성 과정에서 대화 상태나 사용자 입력이 변경되어서는 안 된다. 설치가 완료되지 않은 환경에서는 명령이 존재한다고 판정하지 않는다.

8. 오류 및 충돌 계약

• 패키지 설치에 필요한 메타데이터가 누락되거나 유효하지 않으면 설치를 성공으로 판정하지 않아야 하며 원인을 확인할 수 있는 오류를 반환해야 한다.
• 지원하지 않는 Python 버전에서는 설치 또는 실행을 정상 동작으로 간주하지 않는다.
• 콘솔 진입점이나 모듈 진입점이 애플리케이션 시작 함수를 찾지 못하면 실행은 실패해야 하며 부분적으로 초기화된 애플리케이션을 성공 상태로 남기지 않아야 한다.
• 의존성 버전 제약을 만족하지 못하는 환경에서는 호환되지 않는 런타임으로 자동 대체하거나 외부 서비스를 호출하지 않는다.
• 테스트 의존성 설치 실패는 제품 런타임 의존성의 정상 설치 실패와 구별되어야 한다.
• 설치 또는 실행 실패 시 생성된 부분 산출물이나 임시 상태를 정본 실행 상태로 취급하지 않는다.
• 패키징 변경으로 별도 대화 요구사항에서 보장하는 동작이나 종료 동작이 달라지면 스캐폴드 인수에 실패한 것으로 판정한다.
• 이 문서와 별도 대화 요구사항 사이에 계약 충돌이 발생하면 프로젝트 실행 기반은 이 문서가, 대화 상호작용은 별도 문서가 정본이며 어느 한쪽의 범위를 임의로 확장하지 않는다.

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

• 프로젝트 패키지의 정본 위치는 src/chat_tui이며 패키지 검색 기준은 src이다.
• 프로젝트 메타데이터는 프로젝트 이름, 버전, 설명, README 위치, 지원 Python 버전 및 런타임 의존성을 제공해야 한다.
• 테스트 의존성은 별도 선택적 의존성 그룹으로 선언되어야 한다.
• 콘솔 인터페이스는 chat-tui 명령에서 애플리케이션의 main 실행 함수를 호출해야 한다.
• 모듈 인터페이스는 python -m chat_tui 실행 시 패키지의 모듈 진입점에서 동일한 main 함수를 호출해야 한다.
• 패키지 공개 버전은 프로젝트 메타데이터의 버전과 일치해야 한다.
• 실행 진입점은 외부 입력을 별도 프로토콜이나 네트워크 인터페이스로 변환하지 않고 로컬 Textual 애플리케이션을 시작한다.
• 테스트 인터페이스는 표준 unittest 검색 방식으로 저장소 테스트를 실행할 수 있어야 하며 별도의 서비스나 데이터 저장소를 요구하지 않는다.
• 대화 메시지와 사용자 입력의 데이터 및 화면 인터페이스 계약은 별도 대화 요구사항 문서에서 정의하며 이 문서에서는 재정의하지 않는다.

10. 하위 호환성

• 기존의 chat-tui 콘솔 실행 방식은 유지되어야 한다.
• 기존의 python -m chat_tui 모듈 실행 방식은 유지되어야 한다.
• Python 3.11 이상 지원 조건과 현재 패키지 이름 및 공개 버전 계약은 유지되어야 한다.
• src 기반 패키지 검색과 애플리케이션 패키지의 공개 버전 노출 방식은 유지되어야 한다.
• 기존 README에 설명된 설치 및 실행 명령은 스캐폴드 정리 이후에도 유효해야 한다.
• 대화 입력, 응답 표시, 빈 입력 처리, 입력창 초기화 및 종료와 같은 상호작용 동작은 별도 대화 요구사항 문서의 정본으로 유지하며 이 문서에서 상세히 반복하지 않는다.
• 새 외부 의존성, 외부 연동, 배포 방식 또는 실행 환경을 추가하지 않는다.
• 스캐폴드 문서의 변경은 프로젝트 구조, 패키징 및 실행 진입점의 범위를 넘어 대화 동작의 의미를 변경해서는 안 된다.

11. 검증 계획

Python 3.11 이상 환경에서 패키지 설치와 메타데이터 정합성을 검증한다. 소스 디렉터리 기반 패키지 검색, 런타임 의존성, 선택적 테스트 의존성, 공개 버전이 선언된 계약과 일치하는지 확인한다. 모듈 실행과 콘솔 실행이 동일한 애플리케이션 시작 함수를 호출하는지 확인하고, 기존 저장소 테스트를 실행하여 대화 입력, 응답 표시, 빈 입력 무시, 입력창 초기화 및 종료 동작이 변경되지 않았는지 회귀 검증한다. 테스트 실행 결과와 설치 검증 결과는 실행한 커밋, 환경, 실행 시각 및 성공 여부를 별도 증거로 기록하며, 실행하지 않은 검증을 통과로 간주하지 않는다.

테스트 추적성 계약

테스트 정의:

Test ID: TC-001-001
Verifies:
- REQ-001.01-AC01
- REQ-001.01-AC02
- REQ-001.02-AC01
- REQ-001.03-AC01
Test reference: pyproject.toml 설정 검토 및 python -m unittest discover -s tests -v
Automated: 기존 패키징 및 실행 진입점 검증 테스트를 사용한다.

실행 증거:

Test ID: TC-001-001
Requirement revision: REQ-001@0.1
Commit: d0ac7fc7bcfaf402bbda24776f051fa9992993e1
Environment: Python 3.11 이상, setuptools 기반 설치 환경
Result: 미실행
Executed at: 문서 작성 시점에는 실행 증거를 기록하지 않음

12. 추적성

근거는 Gitea 이슈 #8의 요구사항 재작업 요청과 저장소의 프로젝트 메타데이터, 패키지 구조, 실행 진입점 선언 및 기존 테스트다. 이 문서는 프로젝트 스캐폴드, 패키징, 모듈 실행과 콘솔 실행 진입점만 추적한다. 입력 정규화, 메시지 누적, 고정 응답 선택과 표시, 빈 입력 무시, 입력창 초기화 및 종료 동작의 상세 규칙과 수용 기준은 분리된 대화 상호작용 문서에서만 추적한다. 두 문서는 실행 기반과 대화 동작의 선행 관계만 공유하며 동일한 기능 규칙이나 수용 기준을 반복하지 않는다. 기존 승인 이력은 승인 기록에 보존한다.

13. 확정된 결정

기존 프로젝트 스캐폴드의 의미와 승인 이력을 보존하고, 혼재되어 있던 대화 상호작용 요구사항과 수용 기준은 별도 문서로 분리한다. 이 문서의 정본 범위는 패키지 구조, 패키징 메타데이터와 두 실행 진입점으로 한정한다. 애플리케이션 코드, 테스트 동작, 고정 응답 문구, 입력 처리 순서, 사용자 인터페이스 동작, 외부 연동, 의존성, 배포 환경은 변경하지 않는다.

14. 미결 사항

없음

15. 승인 기록

상태는 승인이다. 기존 승인 주체인 spec-agent와 기존 승인 근거를 보존하며, 이번 문서 정리는 승인 상태를 초안으로 되돌리지 않는다. 승인된 프로젝트 스캐폴드 범위와 기존 승인 이력은 유지하고, 대화 상호작용을 별도 요구사항 문서로 분리한 변경만 추적한다.