Skip to content

AGENTS.md

Latest commit

 

History

History
148 lines (119 loc) · 7.63 KB

AGENTS.md

File metadata and controls

148 lines (119 loc) · 7.63 KB
Raw

Vigilance Weekly — 에이전트 작업 지침

프로젝트 목적

이 프로젝트는 팀에서 공용으로 사용하는 한국어 기반의 문헌·규제정보 모니터링 서비스다.

  • 로그인하지 않은 방문자도 최신 리포트와 지난 리포트를 볼 수 있다.
  • 로그인한 팀원은 공용 감시 대상 목록을 관리하고, 리포트 생성을 즉시 실행하거나 예약할 수 있다. 실행 중인 작업의 취소와 기존 리포트 삭제도 가능하다.
  • 감시 대상과 리포트는 사용자별 데이터가 아니라 사이트 전체의 공용 데이터다. owner_email 같은 기존 데이터베이스 열은 감사 및 호환성 목적으로 남아 있지만, 이를 근거로 데이터를 사용자별로 분리하면 안 된다.
  • 정기 실행은 매주 월요일 오전 06:00에 Asia/Seoul 시간대를 기준으로 시작한다.
  • 관리자는 한국 날짜와 시각을 정확히 지정하여 일회성 실행을 예약할 수 있다.
  • 리포트 생성이 30분을 초과하면 실패 상태가 되어야 한다. 실행 중인 작업은 사용자가 취소할 수 있어야 한다.
  • 같은 ISO 주차에 여러 리포트가 존재할 수 있다. 이때 2026년 31주차, 2026년 31주차 (2)와 같은 이름을 사용한다.
  • 홈 화면에 처음 접속했을 때 가장 최근에 완료된 리포트를 표시한다.

사용자가 명시적으로 요구사항을 변경하지 않는 한 위 원칙을 유지한다.

기술 구성과 주요 경로

  • Node.js >=22.13.0, pnpm, TypeScript
  • vinext/Vite와 Cloudflare Workers에서 실행되는 Next.js 호환 앱
  • Drizzle ORM을 통해 사용하는 Cloudflare D1
  • 화면과 경로 처리기: app/
  • 모니터링 수집 및 예약 실행: worker/monitoring.ts
  • Worker 진입점: worker/index.ts
  • 데이터베이스 스키마: db/schema.ts
  • D1 마이그레이션: drizzle/
  • 로컬·운영 바인딩과 cron 설정: vite.config.ts
  • 배포 프로젝트 식별 정보: .openai/hosting.json
  • 렌더링 및 빌드 검사: tests/

현재 README.md에는 초기 스타터 프로젝트 설명이 많이 남아 있다. README.md와 이 문서 또는 실제 구현이 충돌하면 이 문서와 실제 구현을 우선한다.

배포 시 반드시 지킬 사항

.openai/hosting.json에는 기존 운영 사이트와 D1 바인딩을 식별하는 정보가 들어 있다. 이 파일은 Git에 포함하고, project_id를 임의로 만들거나 교체하지 않는다. 다른 PC에서 배포할 때도 같은 파일을 사용해야 한다. 운영 데이터는 Git 저장소가 아닌 D1에 저장된다.

이 프로젝트는 OpenAI Sites로 호스팅된다. 배포할 때는 사용 가능한 Sites 빌드·호스팅 절차를 따른다. 검증한 소스 상태를 정확히 전송하고, 해당 상태로 버전을 저장한 다음 그 저장된 버전을 배포한다. Sites의 모든 배포 URL은 운영 환경으로 간주한다.

인증정보, 임시 배포 압축 파일 및 로컬 데이터베이스 상태를 Git에 포함하지 않는다. 특히 다음 항목을 커밋하지 않는다.

  • .env*
  • .openai/site-version.tgz
  • .wrangler/
  • dist/, .vinext/, node_modules/
  • tsconfig.tsbuildinfo

모니터링 및 예약 실행 규칙

  • vite.config.ts의 1분 단위 cron은 의도된 설정이다. Worker를 주기적으로 깨워 정확한 시각의 일회성 예약을 처리하며, 실제 실행 필요 여부는 runScheduledMonitoring()이 판단한다.
  • 주간 정기 실행 여부는 서버의 로컬 시간이나 UTC가 아닌 Asia/Seoul을 기준으로 판단한다.
  • 동일 주차의 trigger_type = 'scheduled' 정기 실행은 한 번만 생성되도록 멱등성을 보장한다.
  • 수동 실행과 일회성 예약 실행은 해당 주차에 기존 리포트가 있어도 다음 순번의 리포트를 만들 수 있다.
  • 수집을 시작하기 전에 현재 활성화된 공용 감시 대상 목록을 실행 기록에 스냅샷으로 저장한다.
  • PubMed 문헌 결과에는 PMID, 제목, 저자, 학술지, 출판일, DOI, 초록, 감시 대상, 분류 및 정상적으로 작동하는 PubMed 원문 페이지 링크를 보존한다.
  • 진행률, 현재 단계, 완료 단계 수, 실행 시각, 일부 출처 수집 실패 경고, 취소 및 타임아웃 상태가 화면과 데이터에서 서로 일관되어야 한다.
  • 취소와 삭제 API는 로그인을 요구한다. 공개 리포트 열람 경로는 로그인 없이 계속 이용할 수 있어야 한다.

데이터베이스 변경 규칙

db/schema.ts를 변경할 때 다음 절차를 따른다.

  1. pnpm db:generate로 새로운 Drizzle 마이그레이션을 생성한다.
  2. 생성된 SQL과 메타데이터를 직접 검토한다.
  3. 이미 배포된 마이그레이션을 수정하거나 삭제하지 않는다.
  4. 기존 운영 D1 데이터베이스를 유지해야 하므로, 가능한 한 추가 방식의 하위 호환 변경을 사용한다.

제품 요구사항이 명시적으로 바뀌지 않는 한 감시 대상 및 리포트 조회에 사용자별 조건을 추가하지 않는다. 인증은 관리 기능을 보호하기 위한 것이며, 사이트 데이터를 사용자별로 분리하기 위한 것이 아니다.

화면 및 사용성 원칙

  • 사용자에게 표시되는 문구는 한국어로 작성하고 파일은 UTF-8로 저장한다.
  • 감시 대상 관리 화면은 약물이 10개를 넘어도 사용하기 편해야 하며 좁은 화면에서도 정상적으로 동작해야 한다.
  • 감시 대상 관리와 공개 리포트 보기 등 주요 이동 버튼의 높이를 일관되게 유지한다.
  • 문헌 항목을 클릭하면 유용한 상세정보를 확인할 수 있어야 하며, 별도로 PubMed 원문 페이지로 이동할 수 있어야 한다.
  • 로딩, 데이터 없음, 대기, 실행 중, 완료, 취소, 실패, 일부 성공 및 삭제 상태에 대해 명확한 피드백을 제공한다.
  • 운영 데이터에 샘플 리포트나 샘플 감시 대상을 추가하지 않는다.

로컬 작업 및 검증

pnpm을 사용하고 잠금 파일을 유지한다.

pnpm install
pnpm lint
pnpm build

변경 내용에 맞는 집중 검사도 함께 수행한다. 배포 전에는 최소한 다음 항목을 확인한다.

  1. TypeScript 및 빌드 검증을 실행한다.
  2. 리포트나 홈 화면 출력이 변경되면 렌더링된 HTML 테스트를 실행한다.
  3. git diff를 검토하고 사용자의 관련 없는 기존 변경을 보존한다.
  4. 관련 화면을 변경했다면 비로그인 공개 리포트 열람과 로그인 관리 기능을 모두 확인한다.
  5. 예약 실행을 변경했다면 다음 월요일까지 기다리지 말고 가까운 미래의 한국 날짜와 시각으로 일회성 실행을 예약한다. 리포트가 정확히 하나 생성되고 최종 상태까지 진행되는지 확인한다.

Windows에서는 패키지 스크립트의 환경변수 지정 문법이 제공된 작업공간 런타임에 따라 달라질 수 있다. 셸 문법 때문에만 스크립트가 실패하면 앱의 동작을 변경하지 말고, 동일한 환경변수를 지정하여 해당 pnpm 실행 파일을 직접 실행한다.

다른 PC로 작업을 이어갈 때

이 작업공간에는 아직 팀이 소유한 일반 Git 원격 저장소가 없을 수 있다. 다른 PC로 옮기기 전에 팀이 소유한 비공개 저장소를 사용한다. 각 PC에서는 작업 시작 전에 최신 변경을 가져오고, 검증을 마친 변경을 논리적인 단위로 커밋한 뒤 푸시한다.

임시 배포 인증정보를 Git 원격 저장소 주소에 사용하거나 저장하면 안 된다.