AGENTS.md

프로젝트 개요

프로토콜이 없는 입력에는 https://를 자동으로 붙인다.
http://, https://뿐 아니라 obsidian://, mailto:, tel: 같은 커스텀 프로토콜도 허용한다.
javascript:, data:, vbscript:처럼 위험한 스킴은 차단한다.
동일한 원본 URL이 이미 있으면 새 행을 만들지 말고 기존 단축 URL을 재사용한다.
링크 생성 또는 중복 감지 후 단축 URL과 복사 버튼을 입력 영역 아래에 표시한다.
다크 모드는 system, light, dark를 지원한다. 명시적인 사용자 선택만 localStorage에 저장하고, system 상태에서는 운영체제 설정 변경을 따른다.
화면 문구는 자연스러운 한국어를 사용하고 모바일 및 키보드 접근성을 유지한다.

기능 또는 템플릿을 변경한 뒤 전체 테스트를 실행한다.

.\.venv\Scripts\python.exe -m pytest -q

Linux 또는 WSL에서는 다음 명령을 사용한다.

.venv/bin/python -m pytest -q

static/theme.js를 변경했다면 JavaScript 문법 검사도 실행한다.

node --check static/theme.js

포맷 변경 후에는 git diff --check를 실행한다. 작업 완료 전 git status --short와 git diff를 다시 확인한다.

개발 서버는 다음 주소에서 실행한다.

http://127.0.0.1:5000

Windows 실행 예시:

.\.venv\Scripts\python.exe -m flask --app app run --host 0.0.0.0 --port 5000

서버를 시작하거나 재시작하기 전에 포트 5000의 기존 리스너를 확인한다.
이 환경에서는 터미널의 Ctrl+C가 Flask 하위 프로세스를 종료하지 못할 수 있다. 종료 후 반드시 실제 포트 점유 상태를 재확인한다.
중복 서버가 있으면 이 프로젝트에서 실행한 정확한 PID만 종료한다. 관련 없는 프로세스를 종료하지 않는다.
서버 실행 후 포트 5000을 점유한 리스너가 정확히 하나인지 확인한다.
Python 또는 템플릿 변경 후 실행 중인 서버가 이전 코드를 제공하면 단일 프로세스로 재시작한다. 정적 파일 변경은 일반적으로 재시작 없이 반영된다.