Spec Kit
Constitution ( 규칙, 기준: Constitution.md ) -> Specify ( 요구사항: spec.md, Branch ) / Clarify -> Plan ( 물리적인 폴더 구조, 기술스택정보: plan.md, datamodel.md ) -> Tasks ( tasks.md ) -> Implement ( branch 완성 )
출처; 임정환 교수님
에이전틱 코딩
지금 내용은 내일 또 어떻게 바뀔지 모름
https://www.palantir.com/docs/foundry/ai-fde/overview
Palantir
AI FDE - the AI-powered forward deployed engineer - is an interactive agent that operates Foundry for you through conversational commands. AI FDE...
www.palantir.com
https://github.com/github/spec-kit
GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development
💫 Toolkit to help you get started with Spec-Driven Development - github/spec-kit
github.com
디버깅
https://www.anthropic.com/claude/opus
Claude Opus 4.5
Hybrid reasoning model that pushes the frontier for coding and AI agents, featuring a 200K context window
www.anthropic.com
https://openai.com/ko-KR/index/introducing-gpt-5-2-codex/
forward deployed engineer
Agent 가 통제되지 않으면 청구서 harness
Harness: AI for DevOps, Testing, AppSec, and Cost Optimization
Harness is a unified, end-to-end AI software delivery platform to manage the SDLC using purpose-built AI agents.
www.harness.io
따라야하는 규범을 만듬 -> Agent harness
https://github.com/langchain-ai/deepagents
GitHub - langchain-ai/deepagents: Deep Agents is an agent harness built on langchain and langgraph. Deep Agents are equipped wit
Deep Agents is an agent harness built on langchain and langgraph. Deep Agents are equipped with a planning tool, a filesystem backend, and the ability to spawn subagents - making them well-equipped...
github.com
Human-in-the-loop
https://docs.langchain.com/oss/python/langchain/human-in-the-loop
Human-in-the-loop - Docs by LangChain
The Human-in-the-Loop (HITL) middleware lets you add human oversight to agent tool calls. When a model proposes an action that might require review — for example, writing to a file or executing SQL — the middleware can pause execution and wait for a de
docs.langchain.com
https://blog.deskroom.so/platform/deskroom-supports-ontology-for-ai-driven-decision-making
조직 데이터를 이해하는 LLM의 시작점: 온톨로지(Ontology) - Deskroom | 블로그
데스크룸은 AI 기반 의사결정 플랫폼입니다. 온톨로지로 파편화된 데이터를 연결하고, 감이 아닌 데이터와 AI에 기반한 정확한 기업 의사결정을 돕습니다.
blog.deskroom.so
AI 시대에 작년은 조선시대, 재작년은 석기시대
LLM 다음엔 VLM
Visual Question Answering
Visual Question Answering
visualqa.org
Vision-Language Model
https://www.ibm.com/kr-ko/think/topics/vision-language-models
비전 언어 모델(VLM)이란 무엇인가요? | IBM
비전 언어 모델(VLM)은 컴퓨팅 비전과 자연어 처리(NLP) 기능을 결합한 AI 모델입니다.
www.ibm.com
https://huggingface.co/skt/A.X-K1
skt/A.X-K1 · Hugging Face
We’re on a journey to advance and democratize artificial intelligence through open source and open science.
huggingface.co
https://arxiv.org/abs/2311.07911
Instruction-Following Evaluation for Large Language Models
One core capability of Large Language Models (LLMs) is to follow natural language instructions. However, the evaluation of such abilities is not standardized: Human evaluations are expensive, slow, and not objectively reproducible, while LLM-based auto-eva
arxiv.org
https://huggingface.co/LGAI-EXAONE/K-EXAONE-236B-A23B
LGAI-EXAONE/K-EXAONE-236B-A23B · Hugging Face
We’re on a journey to advance and democratize artificial intelligence through open source and open science.
huggingface.co
팔란티어(Palantir)의 FDE (Forward Deployed Engineer, 전방 배치 엔지니어)
PS C:\Users\511-14> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
PS C:\Users\511-14> Get-ExecutionPolicy
RemoteSigned
PS C:\Users\511-14> rm -r $HOME\.vscode
PS C:\Users\511-14> rm -r $HOME\AppData\Roaming\Code
PS C:\Users\511-14>
https://code.visualstudio.com/docs/copilot/customization/overview
Customize chat to your workflow
Learn how to customize chat in VS Code with custom instructions, reusable prompt files, and custom agents to align AI responses with your coding practices and project requirements.
code.visualstudio.com
PS C:\Users\511-14> uv python list
cpython-3.15.0a5-windows-x86_64-none <download available>
cpython-3.15.0a5+freethreaded-windows-x86_64-none <download available>
cpython-3.14.2-windows-x86_64-none C:\Python314\python.exe
cpython-3.14.2-windows-x86_64-none C:\ProgramData\chocolatey\bin\python3.14.exe
cpython-3.14.2-windows-x86_64-none <download available>
cpython-3.14.2+freethreaded-windows-x86_64-none <download available>
cpython-3.13.11-windows-x86_64-none <download available>
cpython-3.13.11+freethreaded-windows-x86_64-none <download available>
cpython-3.12.12-windows-x86_64-none <download available>
cpython-3.11.14-windows-x86_64-none <download available>
cpython-3.10.19-windows-x86_64-none <download available>
cpython-3.9.25-windows-x86_64-none <download available>
cpython-3.8.20-windows-x86_64-none <download available>
pypy-3.11.13-windows-x86_64-none <download available>
pypy-3.10.16-windows-x86_64-none <download available>
pypy-3.9.19-windows-x86_64-none <download available>
pypy-3.8.16-windows-x86_64-none <download available>
graalpy-3.12.0-windows-x86_64-none <download available>
graalpy-3.11.0-windows-x86_64-none <download available>
graalpy-3.10.0-windows-x86_64-none <download available>
PS C:\Users\511-14>
PS C:\Users\511-14> uv tool list
No tools installed
PS C:\Users\511-14>
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
PS C:\Users\511-14> uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Resolved 20 packages in 177ms
Updated https://github.com/github/spec-kit.git (9111699cd27879e3e6301651a03e502ecb6dd65d)
Built specify-cli @ git+https://github.com/github/spec-kit.git@9111699cd27879e3e6301651a03e502ecb6dd65d
Prepared 20 packages in 4.75s
Installed 20 packages in 197ms
+ anyio==4.12.1
+ certifi==2026.1.4
+ click==8.3.1
+ colorama==0.4.6
+ h11==0.16.0
+ httpcore==1.0.9
+ httpx==0.28.1
+ idna==3.11
+ markdown-it-py==4.0.0
+ mdurl==0.1.2
+ platformdirs==4.5.1
+ pygments==2.19.2
+ readchar==4.2.1
+ rich==14.2.0
+ shellingham==1.5.4
+ socksio==1.0.0
+ specify-cli==0.0.22 (from git+https://github.com/github/spec-kit.git@9111699cd27879e3e6301651a03e502ecb6dd65d)
+ truststore==0.10.4
+ typer==0.21.1
+ typing-extensions==4.15.0
Installed 1 executable: specify
PS C:\Users\511-14>
PS C:\Users\511-14> uv tool list
specify-cli v0.0.22
- specify
PS C:\Users\511-14>
PS C:\Users\511-14> npx create-next-app@latest todolist-app --typescript --eslint --tailwind --app --disable-git
Need to install the following packages:
create-next-app@16.1.4
Ok to proceed? (y) y
√ Would you like to use React Compiler? ... No / Yes
√ Would you like your code inside a `src/` directory? ... No / Yes
√ Would you like to customize the import alias (`@/*` by default)? ... No / Yes
Creating a new Next.js app in C:\Users\511-14\todolist-app.
Using npm.
Initializing project with template: app-tw
Installing dependencies:
- next
- react
- react-dom
Installing devDependencies:
- @tailwindcss/postcss
- @types/node
- @types/react
- @types/react-dom
- babel-plugin-react-compiler
- eslint
- eslint-config-next
- tailwindcss
- typescript
added 357 packages, and audited 358 packages in 20s
141 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
Generating route types...
✓ Types generated successfully
Skipping git initialization.
Success! Created todolist-app at C:\Users\511-14\todolist-app
PS C:\Users\511-14>
Ctrl+Shift+P
PS C:\Users\511-14\todolist-app> specify init .
███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗ ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
███████╗██████╔╝█████╗ ██║ ██║█████╗ ╚████╔╝
╚════██║██╔═══╝ ██╔══╝ ██║ ██║██╔══╝ ╚██╔╝
███████║██║ ███████╗╚██████╗██║██║ ██║
╚══════╝╚═╝ ╚══════╝ ╚═════╝╚═╝╚═╝ ╚═╝
GitHub Spec Kit - Spec-Driven Development Toolkit
Warning: Current directory is not empty (13 items)
Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N]: y
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Specify Project Setup │
│ │
│ Project todolist-app │
│ Working Path C:\Users\511-14\todolist-app │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Selected AI assistant: copilot
Selected script type: ps
Initialize Specify Project
├── ● Check required tools (ok)
├── ● Select AI assistant (copilot)
├── ● Select script type (ps)
├── ● Fetch latest release (release v0.0.90 (57,893 bytes))
├── ● Download template (spec-kit-template-copilot-ps-v0.0.90.zip)
├── ● Extract template
├── ● Archive contents (39 entries)
├── ● Extraction summary (temp 3 items)
├── ○ Ensure scripts executable
├── ● Cleanup
├── ● Initialize git repository (initialized)
└── ● Finalize (project ready)
Project ready.
╭─────────────────────────────────────────────── Agent Folder Security ────────────────────────────────────────────────╮
│ │
│ Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder │
│ within your project. │
│ Consider adding .github/ (or parts of it) to .gitignore to prevent accidental credential leakage. │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── Next Steps ─────────────────────────────────────────────────────╮
│ │
│ 1. You're already in the project directory! │
│ 2. Start using slash commands with your AI agent: │
│ 2.1 /speckit.constitution - Establish project principles │
│ 2.2 /speckit.specify - Create baseline specification │
│ 2.3 /speckit.plan - Create implementation plan │
│ 2.4 /speckit.tasks - Generate actionable tasks │
│ 2.5 /speckit.implement - Execute implementation │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────── Enhancement Commands ────────────────────────────────────────────────╮
│ │
│ Optional commands that you can use for your specs (improve quality & confidence) │
│ │
│ ○ /speckit.clarify (optional) - Ask structured questions to de-risk ambiguous areas before planning (run before │
│ /speckit.plan if used) │
│ ○ /speckit.analyze (optional) - Cross-artifact consistency & alignment report (after /speckit.tasks, before │
│ /speckit.implement) │
│ ○ /speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity, and │
│ consistency (after /speckit.plan) │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
PS C:\Users\511-14\todolist-app>
모든 AI 응답(설명/요약/진행 보고/결과 보고/산출물)은 한국어로 작성합니다.
커밋 메시지 포맷에서 type(scope)는 영어로, 본문 내용은 한국어로 작성합니다.
type: feat, fix, docs, refactor, test, chore
scope: const, spec, plan, task, impl
단, 브랜치명, 파일명, 폴더명, 코드 내 식별자(변수/함수/타입/컴포넌트명)는 영어를 사용합니다.
프로젝트에 대한 헌장, 헌법 작성
https://code.visualstudio.com/docs/copilot/customization/custom-instructions
Use custom instructions in VS Code
Learn how to create custom instructions for GitHub Copilot Chat in VS Code to ensure AI responses match your coding practices, project requirements, and development standards.
code.visualstudio.com
https://github.com/github/awesome-copilot/tree/main
GitHub - github/awesome-copilot: Community-contributed instructions, prompts, and configurations to help you make the most of Gi
Community-contributed instructions, prompts, and configurations to help you make the most of GitHub Copilot. - github/awesome-copilot
github.com
https://github.com/microsoft/playwright
GitHub - microsoft/playwright: Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and
Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API. - GitHub - microsoft/playwright: Playwright is a framework for Web Testi...
github.com
한 팀에선 git merge 방식을 통일해 사용함.
세 가지 방식 요약 비교
|
구분
|
Fast-forward
|
3-way merge
|
Squash merge
|
|
병합 커밋
|
없음
|
있음
|
없음
|
|
히스토리
|
직선
|
분기 구조 유지
|
직선
|
|
브랜치 기록
|
없음
|
있음
|
없음
|
|
충돌 가능성
|
없음
|
있음
|
있음
|
|
주 사용 환경
|
단순 작업
|
협업
|
정리 목적
|
실무에서의 핵심 포인트
- FF merge
- → 개인 브랜치, 단기 작업
- 3-way merge
- → 팀 협업, 추적 가능한 히스토리 필요 시
- Squash merge
- → PR 단위 히스토리 정리
PS C:\Users\511-14\todolist-app> npm test
> todolist-app@0.1.0 test
> vitest
DEV v4.0.18 C:/Users/511-14/todolist-app
✓ tests/unit/page.test.tsx (3 tests) 118ms
✓ Home Page (3)
✓ renders the main heading 84ms
✓ renders the Next.js logo 3ms
✓ contains links to templates and learning center 30ms
Test Files 1 passed (1)
Tests 3 passed (3)
Start at 16:24:58
Duration 1.24s (transform 40ms, setup 106ms, import 199ms, tests 118ms, environment 665ms)
PASS Waiting for file changes...
press h to show help, press q to quit
PS C:\Users\511-14\todolist-app> npm run test:coverage
> todolist-app@0.1.0 test:coverage
> vitest --coverage
DEV v4.0.18 C:/Users/511-14/todolist-app
Coverage enabled with v8
✓ tests/unit/page.test.tsx (3 tests) 143ms
✓ Home Page (3)
✓ renders the main heading 102ms
✓ renders the Next.js logo 3ms
✓ contains links to templates and learning center 37ms
Test Files 1 passed (1)
Tests 3 passed (3)
Start at 16:28:00
Duration 1.42s (transform 35ms, setup 115ms, import 240ms, tests 143ms, environment 704ms)
% Coverage report from v8
----------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
page.tsx | 100 | 100 | 100 | 100 |
----------|---------|----------|---------|---------|-------------------
PASS Waiting for file changes...
press h to show help, press q to quit
PS C:\Users\511-14\todolist-app> npm run test:e2e
> todolist-app@0.1.0 test:e2e
> playwright test
[WebServer] ⚠ Warning: Next.js inferred your workspace root, but it may not be correct.
[WebServer] We detected multiple lockfiles and selected the directory of C:\Users\511-14\package-lock.json as the root directory.
[WebServer] To silence this warning, set `turbopack.root` in your Next.js config, or consider removing one of the lockfiles if it's not needed.
[WebServer] See https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack#root-directory for more information.
[WebServer] Detected additional lockfiles:
[WebServer] * C:\Users\511-14\todolist-app\package-lock.json
[WebServer]
Running 9 tests using 9 workers
9 passed (7.1s)
To open last HTML report run:
npx playwright show-report
PS C:\Users\511-14\todolist-app>
Spec Kit
Constitution ( 규칙, 기준: Constitution.md ) -> Specify ( 요구사항: spec.md ) / Clarify -> Plan ( 물리적인 폴더 구조, 기술스택정보: plan.md, datamodel.md ) -> Tasks ( tasks.md ) -> Implement ( branch 완성 )
{
"chat.promptFilesRecommendations": {
"speckit.constitution": true,
"speckit.specify": true,
"speckit.clarify": true,
"speckit.plan": true,
"speckit.tasks": true,
"speckit.analyze": true,
"speckit.implement": true
},
"chat.tools.terminal.autoApprove": {
".specify/scripts/bash/": true,
".specify/scripts/powershell/": true
}
}
\.specify\memory\constitution.md
.github\copilot-instructions.md
# Copilot Instructions - todolist-app
## 언어 사용 규칙 (최우선)
**Copilot(AI Coding Agent)의 모든 답변과 설명, 코드 주석, 각종 설정 파일의 주석, Todos는 반드시 한국어로 작성합니다.**
예외 사항 (영어 사용):
- 코드 (변수명, 함수명, 컴포넌트명, 타입명 등)
- 파일명, 폴더명
- 기술 용어의 원어 표기가 더 명확한 경우 괄호 안에 병기 가능 (예: "상태 관리(state management)")
좋은 예시:
```
✅ "이 컴포넌트는 useState 훅을 사용하여 상태를 관리합니다"
✅ "TodoList 컴포넌트를 생성하겠습니다"
❌ "This component uses useState hook to manage state"
❌ "Will create a TodoList component"
```
### 커밋 메시지 형식
```
type(scope): "한국어 설명"
```
- **type**: feat, fix, docs, refactor, test, chore
- **scope**: const, spec, plan, task, impl
예시:
```
feat(impl): "TodoList 컴포넌트 구현"
fix(task): "타입 오류 수정"
test(spec): "E2E 테스트 추가"
docs(const): "README 업데이트"
```
## 프로젝트 개요
Next.js 16 (App Router) 기반의 todolist 애플리케이션입니다.
### 핵심 기술 스택
- **프레임워크**: Next.js 16.1.4 (App Router)
- **언어**: TypeScript 5 (strict mode)
- **UI 라이브러리**: React 19
- **스타일링**: Tailwind CSS 4
- **최적화**: React Compiler 활성화 (`next.config.ts`)
- **폰트**: Geist Sans, Geist Mono (자동 최적화)
### 디렉토리 구조
```
todolist-app/
├── .github/ # GitHub 설정
│ ├── copilot-instructions.md # Copilot AI 지침서 (이 문서)
│ ├── agents/ # Spec Kit 에이전트 파일 (9개)
│ │ ├── speckit.analyze.agent.md
│ │ ├── speckit.checklist.agent.md
│ │ ├── speckit.clarify.agent.md
│ │ ├── speckit.constitution.agent.md
│ │ ├── speckit.implement.agent.md
│ │ ├── speckit.plan.agent.md
│ │ ├── speckit.specify.agent.md
│ │ ├── speckit.tasks.agent.md
│ │ └── speckit.taskstoissues.agent.md
│ └── prompts/ # Spec Kit 프롬프트 파일 (9개)
│ ├── speckit.analyze.prompt.md
│ ├── speckit.checklist.prompt.md
│ ├── speckit.clarify.prompt.md
│ ├── speckit.constitution.prompt.md
│ ├── speckit.implement.prompt.md
│ ├── speckit.plan.prompt.md
│ ├── speckit.specify.prompt.md
│ ├── speckit.tasks.prompt.md
│ └── speckit.taskstoissues.prompt.md
│
├── .vscode/ # VS Code 워크스페이스 설정
│ └── settings.json # Spec Kit 파일 자동 추천 및 스크립트 자동 승인
│
├── .specify/ # Spec Kit: AI 주도 개발 워크플로 도구
│ ├── memory/ # 프로젝트 헌법 및 기억
│ │ └── constitution.md # 프로젝트 핵심 원칙 및 아키텍처 철학
│ ├── scripts/ # 자동화 스크립트
│ │ └── powershell/ # PowerShell 스크립트
│ │ ├── check-prerequisites.ps1 # 사전 요구사항 검사
│ │ ├── common.ps1 # 공통 함수 라이브러리
│ │ ├── create-new-feature.ps1 # 새 기능 개발 워크플로
│ │ ├── setup-plan.ps1 # 계획 단계 설정
│ │ └── update-agent-context.ps1 # AI 에이전트 컨텍스트 업데이트
│ └── templates/ # 문서 템플릿
│ ├── agent-file-template.md # AI 에이전트 파일 템플릿
│ ├── checklist-template.md # 체크리스트 템플릿
│ ├── plan-template.md # 계획(Plan) 문서 템플릿
│ ├── spec-template.md # 명세(Spec) 문서 템플릿
│ └── tasks-template.md # 작업(Tasks) 문서 템플릿
│
├── app/ # Next.js App Router (React Server Components)
│ ├── layout.tsx # 루트 레이아웃 (메타데이터, 폰트, 전역 스타일)
│ ├── page.tsx # 홈 페이지 (/)
│ ├── globals.css # Tailwind 전역 스타일
│ └── favicon.ico # 파비콘
│
├── components/ # 재사용 가능한 React 컴포넌트
│ └── (컴포넌트 파일들) # kebab-case.tsx 형식 (예: todo-list.tsx)
│
├── lib/ # 유틸리티 및 헬퍼 함수
│ └── (유틸리티 파일들) # 비즈니스 로직, 공통 함수
│
├── tests/ # 테스트 파일 (Vitest + Playwright)
│ ├── setup.ts # Vitest 전역 설정 (Testing Library)
│ ├── unit/ # 단위 테스트 (Vitest + jsdom)
│ │ └── page.test.tsx # 컴포넌트/함수 단위 테스트
│ ├── integration/ # 통합 테스트
│ └── e2e/ # E2E 테스트 (Playwright)
│ └── home.spec.ts # 사용자 시나리오 테스트
│
├── public/ # 정적 파일 (이미지, 폰트 등)
│ └── (정적 리소스) # /public URL로 제공 (/logo.png)
│
├── labs/ # 실습용 디렉토리 (git 무시됨)
│ ├── lab-00/ # Git 워크플로 실습 (로컬→GitHub→PR→merge)
│ │ └── README.md # 실습 가이드
│ ├── lab-01/ # 실습 01
│ │ └── README.md
│ ├── lab-02/ # 실습 02
│ │ └── README.md
│ └── lab-03/ # 실습 03
│ └── README.md
│
├── coverage/ # Vitest 테스트 커버리지 리포트 (자동 생성)
├── playwright-report/ # Playwright E2E 테스트 리포트 (자동 생성)
├── test-results/ # Playwright 테스트 결과 (자동 생성)
│
├── .env.example # 환경 변수 예시 (복사하여 .env 생성)
├── .gitignore # Git 무시 패턴
│
├── eslint.config.mjs # ESLint 설정 (코드 품질)
├── next.config.ts # Next.js 설정 (React Compiler 활성화)
├── postcss.config.mjs # PostCSS 설정 (Tailwind 처리)
├── tailwindcss.config.ts # Tailwind CSS 설정
├── tsconfig.json # TypeScript 설정 (strict mode, path alias)
├── vitest.config.ts # Vitest 설정 (단위 테스트)
├── playwright.config.ts # Playwright 설정 (E2E 테스트)
│
├── package.json # 프로젝트 의존성 및 스크립트
└── README.md # 프로젝트 문서
```
**핵심 디렉토리 설명**:
- `.github/`: GitHub 및 Copilot 설정
- `agents/`: Spec Kit 워크플로별 Copilot 에이전트 정의 (analyze, specify, plan, tasks, implement 등)
- `prompts/`: Spec Kit 워크플로별 Copilot 프롬프트 템플릿
- `.vscode/settings.json`: **Spec Kit 통합** - Copilot Chat에서 Spec Kit 파일 자동 추천 및 스크립트 자동 승인 설정
- `.specify/`: **Spec Kit** - AI 주도 개발을 위한 템플릿, 스크립트, 프로젝트 헌법
- `memory/constitution.md`: 프로젝트의 불변 원칙 (Library-First, Test-First 등)
- `scripts/`: 기능 개발 워크플로 자동화 스크립트
- `templates/`: Spec, Plan, Tasks 문서 표준 템플릿
- `app/`: Next.js 16 App Router 기반 페이지/레이아웃 (기본 Server Component)
- `components/`: 재사용 컴포넌트 (Client Component는 `"use client"` 명시)
- `lib/`: 순수 함수, 헬퍼, 비즈니스 로직 (독립 라이브러리)
- `tests/unit/`: 컴포넌트/함수 단위 테스트 (Vitest + Testing Library)
- `tests/integration/`: 통합 테스트
- `tests/e2e/`: 사용자 시나리오 E2E 테스트 (Playwright)
- `public/`: 정적 파일 (`/public/logo.png` → `/logo.png`로 접근)
- `labs/`: 실습용 임시 파일 (Git, 워크플로, 기술 연습용, `.gitignore`에서 제외됨)
### Path Alias
- `@/*` → 프로젝트 루트 (`tsconfig.json`, `vitest.config.ts`에 설정됨)
- 예: `import Home from '@/app/page'`
## 핵심 규칙
- Next.js 16 App Router, React 19, TypeScript strict mode를 엄격히 준수합니다
- React Compiler 활성화 환경: 불필요한 `useMemo`, `useCallback` 사용 지양
- 라이브러리 공식 문서가 필요한 경우 Context7 도구(`mcp_io_github_ups_*`)를 활용합니다: 프롬프트에 `use Context7` 명령어 포함
- 코드 작성 전 기존 패턴과 설정 파일을 확인하여 일관성을 유지합니다
## 개발 워크플로우
### 개발 서버
```bash
npm run dev # localhost:3000에서 개발 서버 시작
```
### 테스팅 전략
#### 단위 테스트 (Vitest)
```bash
npm test # 단위 테스트 실행
npm run test:ui # Vitest UI 모드
npm run test:coverage # 커버리지 리포트 생성
```
**설정 포인트**:
- 환경: `jsdom`
- 글로벌 모드 활성화
- Testing Library (`@testing-library/react`, `jest-dom`) 사용
- 테스트 파일: `tests/unit/**/*.{test,spec}.{js,ts,jsx,tsx}`
**테스트 작성 패턴** ([tests/unit/page.test.tsx](../tests/unit/page.test.tsx) 참고):
```typescript
import { describe, it, expect } from 'vitest'
import { render, screen } from '@testing-library/react'
describe('Component Name', () => {
it('should...', () => {
render(<Component />)
const element = screen.getByRole(...)
expect(element).toBeInTheDocument()
})
})
```
#### E2E 테스트 (Playwright)
```bash
npm run test:e2e # E2E 테스트 실행
npm run test:e2e:ui # Playwright UI 모드
npm run test:e2e:report # HTML 리포트 보기
```
**설정 포인트**:
- `baseURL`: http://localhost:3000
- 자동 dev 서버 시작 (`webServer` 설정)
- 브라우저: Chromium, Firefox, WebKit
- CI 환경에서 리트라이 2회
**E2E 테스트 작성 패턴** ([tests/e2e/home.spec.ts](../tests/e2e/home.spec.ts) 참고):
```typescript
test.describe('Feature E2E', () => {
test('should...', async ({ page }) => {
await page.goto('/')
await expect(page.getByRole(...)).toBeVisible()
})
})
```
### 빌드컨벤션
### 파일 및 네이밍
- **파일명**: kebab-case (예: `todo-list.tsx`)
- **컴포넌트명**: PascalCase (예: `TodoList`)
- **함수/변수명**: camelCase (예: `handleSubmit`)
### TypeScript
- Strict 모드 활성화, 모든 컴포넌트에 타입 지정
- JSX: `react-jsx` 변환 사용
### React 컴포넌트
- **Server Components 우선**: `app/` 디렉토리는 기본적으로 Server Component
- Client Component 필요 시 파일 상단에 `"use client"` 추가
- React Compiler 활성화로 불필요한 `useMemo`, `useCallback` 지양
### 스타일링
- Tailwind CSS 유틸리티 클래스 사용
- 다크 모드: `dark:` 접두사, 반응형: `sm:`, `md:` 등
- 예: `className="flex min-h-screen items-center dark:bg-black"`
### Next.js 기능
- 이미지: `next/image` 컴포넌트
- 폰트: `next/font/google` 자동 최적화
- 메타데이터: `layout.tsx`의 `Metadata` 객체
## Spec Kit 워크플로
**Spec Kit**은 AI 주도 개발을 체계화하기 위한 도구 모음으로, `.specify/` 디렉토리에 위치합니다.
### 구조 및 역할
#### `.specify/memory/constitution.md`
프로젝트의 불변 원칙과 아키텍처 철학을 정의합니다.
- Library-First: 모든 기능을 독립 라이브러리로 시작
- Test-First: TDD 필수 (테스트 작성 → 승인 → 구현)
- CLI Interface: 라이브러리는 CLI로 기능 제공
- 관찰 가능성, 버저닝, 단순성 등의 핵심 가치
#### `.specify/templates/`
표준화된 문서 템플릿:
- **spec-template.md**: 기능 명세 작성 템플릿
- **plan-template.md**: 구현 계획 템플릿
- **tasks-template.md**: 작업 목록 템플릿
- **checklist-template.md**: 체크리스트 템플릿
- **agent-file-template.md**: AI 에이전트 컨텍스트 파일 템플릿
#### `.specify/scripts/powershell/`
자동화 스크립트:
- **create-new-feature.ps1**: 새 기능 개발 워크플로 자동화
- **setup-plan.ps1**: 계획 단계 초기화
- **update-agent-context.ps1**: AI 에이전트 컨텍스트 업데이트
- **check-prerequisites.ps1**: 개발 환경 체크
- **common.ps1**: 공통 함수 라이브러리
### 사용 시나리오
**새 기능 개발 시**:
```powershell
# 기능 개발 워크플로 시작
.\.specify\scripts\powershell\create-new-feature.ps1 -FeatureName "todo-crud"
```
이 스크립트는 다음을 자동으로 생성합니다:
1. 기능별 디렉토리 구조
2. Spec, Plan, Tasks 문서 (템플릿 기반)
3. AI 에이전트 컨텍스트 파일
**수동으로 템플릿 사용**:
- `.specify/templates/`에서 필요한 템플릿 복사
- 프로젝트 요구사항에 맞게 커스터마이징
- Copilot에게 템플릿을 참조하도록 지시
**Constitution 참조**:
- 아키텍처 결정 시 `.specify/memory/constitution.md` 참조
- 새 원칙 추가 시 팀 합의 후 업데이트
## 일반적인 작업 패턴
### 새 페이지 추가
1. `app/[route]/page.tsx` 생성 (Server Component 기본)
2. 필요 시 `export const metadata: Metadata = {...}` 추가
### 새 컴포넌트 추가
1. `components/` 디렉토리에 파일 생성
2. 단위 테스트 작성: `tests/unit/[component].test.tsx`
3. E2E 영향 시 `tests/e2e/` 업데이트
### 테스트 우선 개발
1. 기능 구현 전 테스트 작성
2. 단위 테스트로 컴포넌트 로직 검증
3. E2E 테스트로 사용자 흐름 검증
TDD에서 User Story는 ‘무엇을 테스트해야 하는가’를 정의하는 가장 상위 수준의 명세다.
.github/instructions
https://code.visualstudio.com/insiders
Download Visual Studio Code Insiders
For early adopters, you can get the latest release of VS Code each day with the Insiders Build. Available on Mac, Linux and Windows.
code.visualstudio.com
Google Antigravity
Google Antigravity - Build the new way
antigravity.google
현재는 고객과 미팅 시작 후 종료 시 개념 증명(PoC, Proof of Concept)를 완료해 보여준다.
바텀업은 속도는 빠르나 방향을 잃기 쉽다
바이브 코딩은 국소 최적화에는 강하지만 시스템에는 취약
요구사항과 코드 사이에는 반드시 소프트웨어 공학적 계층이 필요
시니어 개발자는 그 공백의 위험을 알기에 PRD/FR/UC로 회귀
이는 후퇴가 아니라 복잡도를 관리하는 유일한 방법
바텀업 개발이 실패하는 이유는 코드를 못 짜서가 아니라, 요구사항과 코드 사이의 공학을 생략하기 때문이다.
Harness vs Framework vs Test
| 목적 | 실행·통제·검증 | 개발 규칙 제공 | 결과 검증 |
| 범위 | 환경 전체 | 코드 구조 | 개별 시나리오 |
| 위치 | 시스템 외곽 | 시스템 내부 | Harness 내부 |
| 재현성 | 매우 중요 | 부차적 | 중요 |
구분 Department Division Enterprise
| 기준 | 기능 | 사업/제품 | 전체 조직 |
| 책임 | 부분 | End-to-End | 정책·표준 |
| 의사결정 | 느림 | 빠름 | 느리지만 안정 |
| 중복 | 낮음 | 높음 | 관리 대상 |
| 기술 구조 | 공유 레이어 | 독립 서비스 | 플랫폼/거버넌스 |
바이브코딩은 TDD 가 안되면 개발은 되지만 유지보수가 안됨
TDD 없는 바이브 코딩은 ‘개발’이 아니라 ‘일회성 생산’이다.
✅ 프로젝트 완료 상태 체크
📊 전체 진행률
58/58 작업 완료 (100%) 🎉
🧪 테스트 결과
✅ 단위 테스트: 59개 통과 (0개 실패)
✅ E2E 테스트: 33개 통과 (0개 실패)
✅ 빌드: 성공
✅ 린트: 통과 (1 warning - 무시 가능)
📋 Phase별 완료 현황
Phase 작업 범위 상태 완료 작업
Phase 1-2 Setup & Foundational ✅ 완료 T000-T010, T037 (13개)
Phase 3 US1 MVP (할일 추가) ✅ 완료 T011-T018 (8개)
Phase 4 US2 (완료 토글) ✅ 완료 T019-T024 (6개)
Phase 5 US3 (삭제+Undo) ✅ 완료 T025-T030 (6개)
Phase 6 US4 (필터링) ✅ 완료 T031-T036 (6개)
Phase 7 US5 (localStorage) ✅ 완료 T038-T043 (6개)
Phase 8 US6 (다크모드) ✅ 완료 T044-T049 (6개)
Final 문서/성능/접근성 ✅ 완료 T050-T058 (9개)
🎯 구현된 기능
Core Features
할일 추가 (제목 필수, 설명 선택)
완료 체크/해제 (취소선 스타일)
할일 삭제 + 5초 Undo
필터링 (전체/진행중/완료)
최신 할일이 위로 정렬
Persistence & UX
localStorage 자동 저장/복원
새로고침 후 상태 유지
다크모드 토글 (시스템/라이트/다크)
반응형 UI (모바일/데스크톱)
Quality Assurance
접근성 준수 (ARIA labels, 키보드 조작)
성능 목표 달성 (p95 < 100ms)
TDD 적용 (전체 작업)
에러 처리 (localStorage 실패 대응)
📁 생성된 파일 (주요)
Components (7개):
todo-app.tsx - 메인 앱
todo-form.tsx - 추가 폼
todo-list.tsx - 목록
todo-item.tsx - 개별 항목
todo-filters.tsx - 필터 버튼
theme-toggle.tsx - 테마 토글
Library (5개):
types.ts - 타입 정의
reducer.ts - 상태 관리
validation.ts - 입력 검증
storage.ts - localStorage
helpers.ts - 필터 계산
Tests (3개):
todo-app.test.tsx - 23개 테스트
tests/unit/todo.*.test.ts - 36개 테스트
home.spec.ts - 33개 시나리오
🎨 기술 스택 검증
✅ Next.js 16.1.4 (App Router)
✅ React 19.2.3
✅ TypeScript 5 (strict mode)
✅ Tailwind CSS 4
✅ Vitest 4.0.18 + Playwright 1.58.0
✅ React Compiler 활성화
📈 성능 측정 결과
필터 전환: p95 < 50ms ✅ (목표: 100ms)
완료 토글: p95 < 30ms ✅
할일 추가: p95 < 40ms ✅
초기 렌더링: ~100ms (500개 항목)
📚 문서 완성도
✅ README.md (실행 방법, 기능 설명)
✅ spec.md (명세)
✅ plan.md (계획)
✅ tasks.md (작업 목록)
✅ research.md (성능 측정)
결론: 모든 요구사항 충족 및 테스트 통과. 프로덕션 배포 가능 상태입니다! 🚀
Summarized conversation history
모든 작업이 이미 완료([x])되어 있습니다. 완료 상태를 재확인하기 위해 테스트 실행 결과를 확인하겠습니다.
npm test -- --run 2>&1 | Select-Object -Last 20
npm run test:e2e 2>&1 | Select-Object -Last 15
npm run build 2>&1 | Select-Object -Last 5
완벽합니다! 모든 작업이 완료되어 체크박스도 이미 업데이트되어 있습니다.
📊 현재 진행 현황
✅ 전체 완료 상태: 58/58 작업 (100%)
Phase별 완료 현황:
Phase 작업 범위 작업 수 상태
Phase 1 Setup (공유 인프라) 5개 ✅ 완료 (T000-T004)
Phase 2 Foundational (공통 기반) 8개 ✅ 완료 (T005-T010, T037)
Phase 3 US1 - 할일 추가 MVP 8개 ✅ 완료 (T011-T018)
Phase 4 US2 - 완료 체크/해제 6개 ✅ 완료 (T019-T024)
Phase 5 US3 - 삭제 + Undo 6개 ✅ 완료 (T025-T030)
Phase 6 US4 - 필터링 6개 ✅ 완료 (T031-T036)
Phase 7 US5 - localStorage 6개 ✅ 완료 (T038-T043)
Phase 8 US6 - 다크모드/반응형 6개 ✅ 완료 (T044-T049)
Final Polish & 문서화 9개 ✅ 완료 (T050-T058)
🧪 테스트 실행 결과
단위 테스트 (Vitest):
✅ 59개 테스트 전부 통과 (6개 파일)
실행 시간: 5.97초
커버리지: validation, reducer, storage, helpers, components
E2E 테스트 (Playwright):
✅ 33개 시나리오 전부 통과 (3개 브라우저)
실행 시간: 21.1초
테스트 범위: 추가/완료/삭제/필터/localStorage/테마/키보드
빌드 검증:
✅ 프로덕션 빌드 성공
정적 페이지 생성 완료
📦 구현된 기능
할일 추가 - 제목/설명 입력, 유효성 검증
완료 토글 - 체크박스로 완료/진행중 전환, 취소선 스타일
삭제 + Undo - 5초 내 실행취소 가능
필터링 - 전체/진행중/완료 필터 전환
자동 저장 - localStorage로 새로고침 시 복원
다크모드 - system/light/dark 테마 지원
반응형 UI - 모바일/데스크톱 대응
키보드 접근성 - Tab/Enter/Space 조작 지원
📄 문서 상태
✅ README.md - 프로젝트 소개 및 실행 가이드
✅ research.md - 성능 측정 결과 (p95 < 50ms)
✅ tasks.md - 전체 58개 작업 체크 완료
✅ spec.md - 요구사항 명세
✅ plan.md - 기술 스택 및 아키텍처
모든 작업이 완료되었고, tasks.md의 모든 체크박스가 [x]로 표시되어 있습니다! 🎉
'푸닥거리' 카테고리의 다른 글
| Spring AI 임베딩과 RAG 구현 (0) | 2026.01.11 |
|---|---|
| Label Shift vs Covariate Shift — 실무 개발자를 위한 10분 가이드 (0) | 2025.08.23 |
| Sequence-to-Sequence (Seq2Seq) 모델 완벽 정리 — RNN vs Transformer 비교 (0) | 2025.08.16 |
| Inductive vs Transductive Learning – 무엇이 다를까? (0) | 2025.07.26 |
| 🔍 RAG(Retrieval-Augmented Generation)란? 검색과 생성의 만남 (0) | 2025.07.23 |
댓글