FE Assistant

기획서, Figma, Jira, API 초안을 입력하면 대상 저장소 기준의 신규 기능 FE 구현 범위를 정리하는 로컬 도구입니다. 프로젝트별 규칙은 대상 저장소의 AGENTS.md 또는 CLAUDE.md를 읽어 반영합니다.

설치

yarn add -D @innovaid-fe/fe-assistant

프로젝트 package.json에 실행 스크립트를 추가합니다.

{
  "scripts": {
    "fe-assistant": "fe-assistant --repo ."
  }
}

실행

yarn fe-assistant

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:5175

옵션

fe-assistant --repo . --port 5175 --env .env.local

• --repo: 분석하고 구현을 실행할 대상 프로젝트 루트입니다.
• --port: 로컬 서버 포트입니다. 기본값은 5175입니다.
• --env: 추가 env 파일입니다. 상대 경로는 --repo 기준으로 해석합니다.
• --cache-dir: 문서와 실행 결과 캐시 위치입니다. 기본값은 .fe-assistant/cache입니다.

Env 설정

패키지에는 빈 값으로 채워진 .env.local 템플릿이 포함됩니다. 설치하면 대상 프로젝트 루트에 .env.local이 없을 때만 자동으로 생성합니다. 이미 .env.local이 있으면 덮어쓰지 않습니다.

실제 토큰은 대상 프로젝트의 .env.local에 채워 넣습니다. 이 파일은 Git에 커밋하지 마세요.

CODEX_BIN=codex
CODEX_MODEL=gpt-5.5
CODEX_REASONING_EFFORT=xhigh
CODEX_SPEED=standard
CODEX_TIMEOUT_MS=300000
CODEX_IMPLEMENT_TIMEOUT_MS=900000
FE_SCOPE_TOOL_PORT=5175
FE_SCOPE_TOOL_MAX_LINK_CHARS=12000
FE_SCOPE_TOOL_MAX_REPO_FILES=420

FIGMA_ACCESS_TOKEN=
NOTION_API_TOKEN=
JIRA_EMAIL=
JIRA_API_TOKEN=

하는 일

• 기획서, Figma, Jira 문서, API 문서 링크를 입력받습니다.
• 링크 본문은 접근 가능한 경우에만 best-effort로 미리 읽습니다.
• Figma 링크는 FIGMA_ACCESS_TOKEN이 있으면 Figma REST API로 읽습니다.
• Notion 링크는 NOTION_API_TOKEN이 있으면 Notion API로 읽습니다.
• Jira 링크는 JIRA_EMAIL과 JIRA_API_TOKEN이 있으면 Jira Cloud API로 읽습니다.
• 필요한 토큰이 없는 서비스 링크가 입력되면 화면에 경고를 표시하고 문서 생성을 막습니다.
• Codex CLI를 읽기 전용으로 실행해 FE 구현 범위 명세를 생성합니다.
• Jira 하위 티켓 생성을 켜면 명세 기준 후보를 먼저 보여주고, 승인한 항목만 하위 티켓으로 생성합니다.
• 개발자가 입력한 수정사항을 반영해 명세를 다시 작성합니다.
• 최종 검수 후 버튼으로 대상 저장소에서 Codex CLI 코드 작성을 실행할 수 있습니다.

공개 패키지 배포

이 패키지는 공개 npm 패키지로 배포할 수 있도록 files 목록을 제한합니다. 배포 전에 반드시 포함 파일을 확인하세요.

npm pack --dry-run
npm publish

npm publish를 실행하면 npm registry의 최신 배포 버전을 확인하고, 필요하면 patch 버전을 자동으로 올린 뒤 공개 배포합니다.

배포 시 prepack 스크립트가 .env.local의 credential 값을 임시로 비운 뒤 tarball 생성이 끝나면 postpack에서 원래 로컬 파일로 되돌립니다.

배포에 포함되면 안 되는 파일:

• 실제 토큰이 들어간 .env.local
• .env.local.fe-assistant-backup
• .cache/
• .fe-assistant/cache/
• 토큰, 내부 문서, 생성된 scope plan 결과

주의

• API 문서가 비공개 링크이면 도구가 본문을 직접 읽지 못할 수 있습니다.
• Figma, Notion, Jira는 일반 링크 fetch가 아니라 토큰 기반 API 접근이 필요합니다.
• 링크 본문을 읽지 못한 경우 요구사항 메모 입력란에 핵심 내용을 붙여 넣으면 더 정확합니다.
• 코드 작성 실행 버튼은 대상 저장소 파일을 수정할 수 있습니다.
• 이 도구는 커밋이나 push를 수행하지 않습니다.