# Copilot Instructions for todolist-app

## Project Overview
This is a Next.js 16 todo list application using the App Router architecture with React 19, TypeScript, and Tailwind CSS v4. The project leverages React Compiler for optimizations and follows modern Next.js conventions.

## Tech Stack
- **Framework**: Next.js 16.1.4 (App Router)
- **React**: 19.2.3 with React Compiler enabled
- **Styling**: Tailwind CSS v4 (new @import syntax in globals.css)
- **TypeScript**: Strict mode enabled
- **Fonts**: Geist Sans & Geist Mono via next/font/google
- **Linting**: ESLint 9 with Next.js TypeScript presets

## Project Structure
```
app/
  layout.tsx    - Root layout with Geist font configuration
  page.tsx      - Main page component
  globals.css   - Tailwind v4 import + theme variables
```

## Development Commands
- `npm run dev` - Start dev server on http://localhost:3000
- `npm run build` - Production build
- `npm run start` - Start production server
- `npm run lint` - Run ESLint

## Key Conventions

### Component Style
- Use React Server Components by default (no 'use client' unless needed)
- Prefer function declarations: `export default function ComponentName()`
- Use TypeScript for all components with explicit types

### Styling Approach
- Tailwind v4 uses `@import "tailwindcss"` syntax in [globals.css](app/globals.css)
- Custom theme variables defined with `@theme inline` directive
- Dark mode via `dark:` prefix with prefers-color-scheme media query
- CSS variables: `--background`, `--foreground` for theme colors
- Use utility-first Tailwind classes directly in JSX

### TypeScript Configuration
- Path alias `@/*` maps to project root
- Strict mode enabled - handle null/undefined explicitly
- Target ES2017 with modern module resolution (bundler mode)

### React Compiler
- Enabled in [next.config.ts](next.config.ts#L4) via `reactCompiler: true`
- Automatically optimizes component re-renders
- Avoid manual useMemo/useCallback unless profiling shows benefit

### Font Management
- Geist fonts loaded in [layout.tsx](app/layout.tsx) as CSS variables
- Applied via className: `${geistSans.variable} ${geistMono.variable}`
- Referenced in CSS as `var(--font-geist-sans)` and `var(--font-geist-mono)`

### ESLint Configuration
- Uses flat config format (eslint.config.mjs)
- Next.js core-web-vitals and TypeScript rules enabled
- Ignores: .next/, out/, build/, next-env.d.ts

## Adding New Features

### Creating New Pages
- Add `.tsx` files to `app/` directory following App Router conventions
- Use Server Components by default, add 'use client' only when using hooks/interactivity
- Export metadata for SEO: `export const metadata: Metadata = {...}`

### Adding Client Components
- Add 'use client' directive at the top of file
- Place in appropriate subdirectory under `app/`
- Use React 19 features (useActionState, useOptimistic, etc.)

### Styling New Components
- Follow existing pattern: use Tailwind utilities with dark mode variants
- Responsive design: use `sm:`, `md:` breakpoints as shown in [page.tsx](app/page.tsx)
- Maintain spacing consistency: gap-4, gap-6, py-32, px-16

## Communication & Commit Conventions

### Language Rules
- **All AI responses** in Korean: explanations, summaries, progress reports, results, deliverables
- **Code identifiers** in English: variable/function/type/component names
- **File/folder/branch names** in English

### 언어 규칙
```
type(scope): 한국어로 작성된 커밋 메시지 제목

한국어로 작성된 상세 설명 (선택사항)
```

**AI응답 메시지 언어**: 한국어  
**코드 식별자 언어**: 영어
**파일/폴더/브랜치 이름 언어**: 영어

**Types**: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`  
**Scopes**: `const`, `spec`, `plan`, `task`, `impl`

**Examples**:
- `feat(impl): 할 일 목록 추가 기능 구현`
- `fix(task): 다크 모드 토글 버그 수정`
- `docs(spec): 프로젝트 구조 문서화`

## Important Notes
- This is a fresh Next.js project - core todo functionality not yet implemented
- React Compiler is enabled - trust automatic optimizations
- Tailwind v4 syntax differs from v3 (note the @import and @theme directives)
- TypeScript strict mode requires explicit type handling

1. 문서 제목

원문	설명
# Copilot Instructions for todolist-app	Markdown의 1단계 제목입니다. 이 문서가 todolist-app 프로젝트를 위한 Copilot 지침서라는 뜻입니다.

이 파일은 AI 코딩 도우미가 프로젝트의 기술 스택, 코드 스타일, 커밋 규칙, 언어 규칙 등을 일관되게 따르도록 작성된 지침 문서입니다.

2. Project Overview

원문	설명
## Project Overview	프로젝트 개요 섹션입니다. 이 프로젝트가 어떤 기술과 구조를 기반으로 하는지 간단히 설명합니다.
This is a Next.js 16 todo list application using the App Router architecture with React 19, TypeScript, and Tailwind CSS v4.	이 프로젝트는 Next.js 16 기반의 Todo List 앱이며, App Router 구조를 사용한다고 설명합니다. React 19, TypeScript, Tailwind CSS v4를 함께 사용합니다.
The project leverages React Compiler for optimizations and follows modern Next.js conventions.	React Compiler를 통해 렌더링 최적화를 활용하며, 최신 Next.js 개발 관례를 따른다는 의미입니다.

핵심은 다음과 같습니다.

프로젝트 유형: Todo List 앱
프레임워크: Next.js
라우팅 방식: App Router
UI 라이브러리: React
언어: TypeScript
스타일링: Tailwind CSS
최적화: React Compiler

프로젝트 개요에서는 이 앱이 단순한 Todo List 앱이지만, 최신 Next.js App Router 구조와 React Compiler까지 사용하는 현대적인 프론트엔드 프로젝트임을 명시하고 있습니다.

3. Tech Stack

원문	설명
## Tech Stack	기술 스택 섹션입니다. 프로젝트에서 사용하는 주요 라이브러리와 도구를 정리합니다.
- Framework: Next.js 16.1.4 (App Router)	프레임워크는 Next.js 16.1.4이며, Pages Router가 아니라 App Router를 사용한다는 뜻입니다.
- React: 19.2.3 with React Compiler enabled	React 19.2.3을 사용하며, React Compiler가 활성화되어 있습니다.
- Styling: Tailwind CSS v4 (new @import syntax in globals.css)	스타일링은 Tailwind CSS v4를 사용합니다. v4에서는 globals.css에서 @import "tailwindcss" 방식으로 Tailwind를 불러옵니다.
- TypeScript: Strict mode enabled	TypeScript strict mode가 활성화되어 있습니다. 타입 안정성을 엄격하게 검사합니다.
- Fonts: Geist Sans & Geist Mono via next/font/google	Next.js의 next/font/google 기능을 사용해 Geist Sans와 Geist Mono 폰트를 불러옵니다.
- Linting: ESLint 9 with Next.js TypeScript presets	ESLint 9를 사용하며, Next.js와 TypeScript에 맞는 규칙 세트를 적용합니다.

이 섹션은 AI에게 “이 프로젝트는 어떤 환경에서 작성되어야 하는가”를 알려줍니다.

특히 중요한 점은 다음입니다.

Next.js 16 + React 19 + Tailwind CSS v4 + TypeScript strict mode

이 조합은 코드 작성 방식에 직접적인 영향을 줍니다.

예를 들어 AI가 Tailwind v3 방식으로 설정 파일을 작성하거나, Pages Router 방식으로 pages/index.tsx를 만들면 프로젝트 구조와 맞지 않게 됩니다. 그래서 이 지침에서 정확한 기술 스택을 명시하는 것이 중요합니다.

4. Project Structure

원문	설명
## Project Structure	프로젝트 폴더 구조를 설명하는 섹션입니다.
<code>```</code>	Markdown 코드 블록 시작입니다. 폴더 구조를 보기 좋게 표시하기 위해 사용합니다.
app/	Next.js App Router의 핵심 폴더입니다. 이 안에 페이지, 레이아웃, 전역 스타일 등이 들어갑니다.
layout.tsx - Root layout with Geist font configuration	app/layout.tsx 파일은 전체 앱에 적용되는 루트 레이아웃입니다. 여기서 Geist 폰트 설정을 합니다.
page.tsx - Main page component	app/page.tsx는 루트 경로 /에 해당하는 메인 페이지 컴포넌트입니다.
globals.css - Tailwind v4 import + theme variables	app/globals.css는 전역 CSS 파일입니다. Tailwind v4 import와 테마 변수를 정의합니다.
<code>```</code>	코드 블록 종료입니다.

이 구조는 Next.js App Router의 기본 구조입니다.

app/
  layout.tsx
  page.tsx
  globals.css

각 파일의 역할은 다음과 같습니다.

파일	역할
layout.tsx	전체 페이지에 공통으로 적용되는 HTML 구조, 폰트, 메타데이터 설정
page.tsx	/ 경로에 표시되는 메인 화면
globals.css	전역 스타일, Tailwind import, CSS 변수 설정

이 프로젝트는 App Router 기반이므로 app/ 디렉터리가 중심입니다. layout.tsx는 전체 앱의 공통 껍데기 역할을 하고, page.tsx는 메인 페이지, globals.css는 전역 스타일을 담당합니다.

5. Development Commands

원문	설명
## Development Commands	개발 중 사용하는 npm 명령어를 정리한 섹션입니다.
- `npm run dev` - Start dev server on http://localhost:3000	개발 서버를 실행하는 명령어입니다. 기본적으로 localhost:3000에서 앱을 확인할 수 있습니다.
- `npm run build` - Production build	배포용 프로덕션 빌드를 생성하는 명령어입니다.
- `npm run start` - Start production server	빌드된 프로덕션 서버를 실행하는 명령어입니다.
- `npm run lint` - Run ESLint	ESLint를 실행하여 코드 스타일과 잠재적 오류를 검사합니다.

각 명령어의 의미는 다음과 같습니다.

npm run dev

개발 중 사용하는 명령어입니다. 코드 수정 후 브라우저에서 바로 결과를 확인할 수 있습니다.

npm run build

배포 가능한 형태로 프로젝트를 빌드합니다. TypeScript 오류나 빌드 오류가 있으면 이 단계에서 실패할 수 있습니다.

npm run start

npm run build 이후 생성된 결과물을 실제 운영 환경처럼 실행합니다.

npm run lint

ESLint를 실행하여 코드 품질을 검사합니다.

이 섹션은 AI가 프로젝트 실행, 빌드, 검사 명령어를 정확히 알 수 있도록 합니다. 특히 Agent가 작업 후 검증을 수행할 때 npm run lint나 npm run build를 사용할 수 있습니다.

6. Key Conventions

원문	설명
## Key Conventions	프로젝트에서 지켜야 할 핵심 개발 규칙을 모아둔 섹션입니다.

이 섹션은 매우 중요합니다.
AI가 단순히 코드를 생성하는 것이 아니라, 프로젝트의 스타일과 설계 원칙에 맞게 코드를 작성하도록 만듭니다.

6-1. Component Style

원문	설명
### Component Style	React 컴포넌트 작성 방식에 대한 규칙입니다.
- Use React Server Components by default (no 'use client' unless needed)	기본적으로 React Server Component를 사용하라는 의미입니다. 클라이언트 기능이 필요할 때만 'use client'를 붙입니다.
- Prefer function declarations: export default function ComponentName()	컴포넌트는 화살표 함수보다 함수 선언식 형태를 선호한다는 규칙입니다.
- Use TypeScript for all components with explicit types	모든 컴포넌트는 TypeScript로 작성하고, 필요한 타입은 명시적으로 선언하라는 뜻입니다.

Server Component 기본 사용

Next.js App Router에서는 기본적으로 컴포넌트가 Server Component입니다.

export default function Page() {
  return <main>Hello</main>;
}

위 코드는 별도로 'use client'를 선언하지 않았기 때문에 Server Component입니다.

반대로 아래처럼 상태, 이벤트, 브라우저 API를 사용해야 한다면 Client Component가 필요합니다.

'use client';

import { useState } from 'react';

export default function TodoInput() {
  const [text, setText] = useState('');

  return <input value={text} onChange={(e) => setText(e.target.value)} />;
}

함수 선언식 선호

지침에서는 다음 형태를 선호합니다.

export default function TodoList() {
  return <div>Todo List</div>;
}

화살표 함수도 가능하지만, 이 프로젝트에서는 함수 선언식을 컨벤션으로 정한 것입니다.

const TodoList = () => {
  return <div>Todo List</div>;
};

export default TodoList;

이 프로젝트에서는 Next.js App Router의 기본 철학에 맞춰 Server Component를 우선 사용합니다. 클라이언트 상태나 이벤트 핸들링이 필요한 경우에만 'use client'를 선언하도록 규칙을 정하고 있습니다.

6-2. Styling Approach

원문	설명
### Styling Approach	스타일링 방식에 대한 규칙입니다.
- Tailwind v4 uses `@import "tailwindcss"` syntax in [globals.css](app/globals.css)	Tailwind CSS v4에서는 globals.css에서 @import "tailwindcss" 문법을 사용합니다.
- Custom theme variables defined with `@theme inline` directive	커스텀 테마 변수는 Tailwind v4의 @theme inline 지시어를 사용해 정의합니다.
- Dark mode via `dark:` prefix with prefers-color-scheme media query	다크 모드는 Tailwind의 dark: 접두사를 사용하고, 사용자의 시스템 설정인 prefers-color-scheme을 기준으로 처리합니다.
- CSS variables: `--background`, `--foreground` for theme colors	배경색과 글자색을 CSS 변수 --background, --foreground로 관리합니다.
- Use utility-first Tailwind classes directly in JSX	JSX 안에서 Tailwind utility class를 직접 사용합니다.

Tailwind v4 import 방식

Tailwind CSS v3에서는 보통 다음과 같은 문법을 사용했습니다.

@tailwind base;
@tailwind components;
@tailwind utilities;

하지만 이 프로젝트는 Tailwind CSS v4 기준이므로 다음 방식을 사용합니다.

@import "tailwindcss";

따라서 AI가 이전 버전 문법으로 코드를 작성하지 않도록 지침에 명시한 것입니다.

CSS 변수 사용

:root {
  --background: #ffffff;
  --foreground: #171717;
}

이런 식으로 색상을 변수로 관리하면 테마 변경이 쉬워집니다.

JSX에서는 다음처럼 Tailwind utility class를 직접 사용합니다.

export default function Page() {
  return (
    <main className="min-h-screen px-16 py-32">
      <h1 className="text-4xl font-bold">Todo List</h1>
    </main>
  );
}

이 프로젝트는 별도의 CSS 파일을 많이 만들기보다, Tailwind의 utility-first 방식을 사용해 JSX 안에서 직접 스타일을 작성합니다. 또한 Tailwind v4 문법을 사용하기 때문에 기존 v3 방식과 혼동하지 않도록 명시하고 있습니다.

6-3. TypeScript Configuration

원문	설명
### TypeScript Configuration	TypeScript 설정 규칙입니다.
- Path alias `@/*` maps to project root	@/ 경로 별칭이 프로젝트 루트를 가리킨다는 의미입니다.
- Strict mode enabled - handle null/undefined explicitly	strict mode가 활성화되어 있으므로 null과 undefined를 명확히 처리해야 합니다.
- Target ES2017 with modern module resolution (bundler mode)	TypeScript 컴파일 타깃은 ES2017이며, 모듈 해석은 bundler mode를 사용합니다.

Path Alias

다음과 같은 상대 경로 대신,

import Button from '../../../components/Button';

다음처럼 쓸 수 있습니다.

import Button from '@/components/Button';

이렇게 하면 폴더 깊이가 깊어져도 import 경로가 깔끔해집니다.

Strict Mode

TypeScript strict mode에서는 다음 코드가 문제가 될 수 있습니다.

function printName(name?: string) {
  console.log(name.toUpperCase());
}

name이 undefined일 수 있기 때문입니다.

안전하게 작성하려면 다음처럼 처리해야 합니다.

function printName(name?: string) {
  if (!name) return;

  console.log(name.toUpperCase());
}

strict mode는 번거로울 수 있지만, 런타임 오류를 사전에 줄여주는 중요한 설정입니다. 특히 null과 undefined를 명시적으로 처리하도록 강제하기 때문에 안정적인 TypeScript 코드를 작성하는 데 도움이 됩니다.

6-4. React Compiler

원문	설명
### React Compiler	React Compiler 관련 규칙입니다.
- Enabled in [next.config.ts](next.config.ts#L4) via `reactCompiler: true`	next.config.ts 파일의 4번째 줄 근처에서 reactCompiler: true 설정을 통해 React Compiler가 활성화되어 있다는 의미입니다.
- Automatically optimizes component re-renders	React Compiler가 컴포넌트 리렌더링을 자동으로 최적화합니다.
- Avoid manual useMemo/useCallback unless profiling shows benefit	성능 측정 결과가 필요하다고 확인되지 않는 한 useMemo, useCallback을 과도하게 사용하지 말라는 뜻입니다.

React Compiler의 의미

기존 React에서는 불필요한 리렌더링을 줄이기 위해 다음과 같은 최적화 코드를 자주 사용했습니다.

const handleClick = useCallback(() => {
  console.log('clicked');
}, []);

또는,

const filteredTodos = useMemo(() => {
  return todos.filter((todo) => todo.done);
}, [todos]);

하지만 React Compiler가 활성화되어 있으면 많은 최적화를 자동으로 처리할 수 있습니다.

따라서 이 프로젝트에서는 다음 원칙을 따릅니다.

무조건 useMemo/useCallback을 붙이지 않는다.
실제로 성능 문제가 확인될 때만 사용한다.

React Compiler가 활성화된 프로젝트에서는 기존처럼 습관적으로 useMemo와 useCallback을 남발할 필요가 없습니다. 실제 성능 측정 결과가 있을 때만 수동 최적화를 적용하는 것이 이 프로젝트의 원칙입니다.

6-5. Font Management

원문	설명
### Font Management	폰트 관리 방식에 대한 섹션입니다.
- Geist fonts loaded in [layout.tsx](app/layout.tsx) as CSS variables	layout.tsx에서 Geist 폰트를 불러오고 CSS 변수로 등록합니다.
- Applied via className: `${geistSans.variable} ${geistMono.variable}`	className에 Geist Sans와 Geist Mono 변수를 적용합니다.
- Referenced in CSS as `var(--font-geist-sans)` and `var(--font-geist-mono)`	CSS에서는 var(--font-geist-sans), var(--font-geist-mono) 형태로 폰트를 참조합니다.

Next.js에서는 next/font/google을 사용해 폰트를 최적화할 수 있습니다.

예시:

import { Geist, Geist_Mono } from 'next/font/google';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

그리고 body에 적용합니다.

<body className={`${geistSans.variable} ${geistMono.variable}`}>
  {children}
</body>

CSS에서는 다음처럼 사용할 수 있습니다.

body {
  font-family: var(--font-geist-sans);
}

폰트는 layout.tsx에서 전역으로 불러오고 CSS 변수로 등록합니다. 이렇게 하면 전체 앱에서 일관된 폰트 시스템을 사용할 수 있고, Next.js의 폰트 최적화 기능도 함께 활용할 수 있습니다.

6-6. ESLint Configuration

원문	설명
### ESLint Configuration	ESLint 설정에 대한 설명입니다.
- Uses flat config format (eslint.config.mjs)	ESLint의 flat config 방식인 eslint.config.mjs를 사용합니다.
- Next.js core-web-vitals and TypeScript rules enabled	Next.js의 Core Web Vitals 규칙과 TypeScript 규칙이 활성화되어 있습니다.
- Ignores: .next/, out/, build/, next-env.d.ts	.next/, out/, build/, next-env.d.ts 파일이나 폴더는 lint 검사에서 제외합니다.

ESLint는 코드 스타일과 잠재적 오류를 검사하는 도구입니다.

예를 들어 다음과 같은 문제를 잡아낼 수 있습니다.

사용하지 않는 변수
잘못된 import
React/Next.js 권장 규칙 위반
TypeScript 타입 관련 문제
접근성 관련 문제 일부

무시 대상은 보통 자동 생성물이거나 빌드 결과물입니다.

무시 대상	이유
.next/	Next.js 빌드 캐시 및 결과물
out/	정적 export 결과물
build/	빌드 산출물
next-env.d.ts	Next.js가 자동 생성하는 타입 선언 파일

7. Adding New Features

원문	설명
## Adding New Features	새로운 기능을 추가할 때 따라야 할 규칙입니다.

이 섹션은 AI가 앞으로 Todo 기능, 페이지, 컴포넌트 등을 추가할 때 참고하는 작업 가이드입니다.

7-1. Creating New Pages

원문	설명
### Creating New Pages	새 페이지를 만드는 방법입니다.
- Add `.tsx` files to `app/` directory following App Router conventions	새 페이지는 app/ 디렉터리에 .tsx 파일로 추가해야 합니다.
- Use Server Components by default, add 'use client' only when using hooks/interactivity	기본은 Server Component이며, hook이나 상호작용이 필요할 때만 Client Component로 만듭니다.
- Export metadata for SEO: `export const metadata: Metadata = {...}`	SEO를 위해 페이지 메타데이터를 export하라는 뜻입니다.

Next.js App Router에서는 폴더 구조가 곧 라우팅 구조입니다.

예를 들어 /about 페이지를 만들고 싶다면 다음처럼 작성합니다.

app/
  about/
    page.tsx

app/about/page.tsx는 /about 경로가 됩니다.

메타데이터는 다음처럼 작성할 수 있습니다.

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'About',
  description: 'About page',
};

export default function AboutPage() {
  return <main>About</main>;
}

App Router에서는 파일 기반 라우팅을 사용합니다. app/about/page.tsx를 만들면 자동으로 /about URL이 생성됩니다. 또한 각 페이지는 metadata를 export하여 SEO 정보를 설정할 수 있습니다.

7-2. Adding Client Components

원문	설명
### Adding Client Components	Client Component를 추가할 때의 규칙입니다.
- Add 'use client' directive at the top of file	파일 최상단에 'use client'를 추가해야 합니다.
- Place in appropriate subdirectory under `app/`	app/ 아래 적절한 하위 디렉터리에 배치합니다.
- Use React 19 features (useActionState, useOptimistic, etc.)	React 19의 기능인 useActionState, useOptimistic 등을 사용할 수 있습니다.

Client Component가 필요한 경우는 다음과 같습니다.

useState 사용
useEffect 사용
클릭 이벤트 처리
input 입력 처리
브라우저 API 사용
낙관적 UI 업데이트
클라이언트 상태 관리

예시:

'use client';

import { useState } from 'react';

export default function TodoForm() {
  const [title, setTitle] = useState('');

  return (
    <form>
      <input
        value={title}
        onChange={(event) => setTitle(event.target.value)}
      />
    </form>
  );
}

중요한 점은 'use client'가 반드시 파일의 최상단에 있어야 한다는 것입니다.

'use client';

이 선언이 있어야 해당 파일이 Client Component로 처리됩니다.

7-3. Styling New Components

원문	설명
### Styling New Components	새 컴포넌트를 스타일링할 때의 규칙입니다.
- Follow existing pattern: use Tailwind utilities with dark mode variants	기존 스타일 패턴을 따르고, Tailwind utility와 dark mode variant를 사용합니다.
- Responsive design: use `sm:`, `md:` breakpoints as shown in [page.tsx](app/page.tsx)	반응형 디자인은 sm:, md: breakpoint를 사용합니다.
- Maintain spacing consistency: gap-4, gap-6, py-32, px-16	간격은 기존 프로젝트에서 사용 중인 gap-4, gap-6, py-32, px-16 등을 기준으로 일관성 있게 유지합니다.

Tailwind에서는 반응형 스타일을 다음처럼 작성합니다.

<div className="flex flex-col gap-4 md:flex-row md:gap-6">
  ...
</div>

의미는 다음과 같습니다.

클래스	의미
flex	flex layout 사용
flex-col	기본 방향은 세로
gap-4	기본 간격은 gap-4
md:flex-row	md 이상 화면에서는 가로 배치
md:gap-6	md 이상 화면에서는 간격을 gap-6으로 변경

새 컴포넌트를 만들 때도 기존 페이지의 간격, 반응형 기준, 다크 모드 패턴을 유지해야 합니다. 이렇게 하면 여러 사람이 작업하거나 AI가 코드를 생성하더라도 UI의 일관성이 유지됩니다.

8. Communication & Commit Conventions

원문	설명
## Communication & Commit Conventions	AI 응답 언어, 코드 식별자 언어, 커밋 메시지 형식을 정의하는 섹션입니다.

이 부분은 특히 AI Agent 환경에서 중요합니다.
코드 작성뿐 아니라 설명 언어, 파일명, 브랜치명, 커밋 메시지까지 통일합니다.

8-1. Language Rules

원문	설명
### Language Rules	언어 사용 규칙입니다.
- All AI responses in Korean: explanations, summaries, progress reports, results, deliverables	AI의 모든 응답은 한국어로 작성해야 합니다. 설명, 요약, 진행 보고, 결과물 모두 한국어입니다.
- Code identifiers in English: variable/function/type/component names	변수명, 함수명, 타입명, 컴포넌트명 같은 코드 식별자는 영어로 작성합니다.
- File/folder/branch names in English	파일명, 폴더명, 브랜치명도 영어로 작성합니다.

이 규칙은 한국어 기반 개발자에게 매우 유용합니다.

예를 들어 설명은 한국어로 합니다.

할 일 목록을 추가하는 컴포넌트입니다.

하지만 코드 식별자는 영어로 작성합니다.

export default function TodoList() {
  const todoItems = [];

  return <div>{todoItems.length}</div>;
}

좋은 예:

const todoItems = [];
function addTodo() {}
type TodoItem = {};

좋지 않은 예:

const 할일목록 = [];
function 할일추가() {}
type 할일항목 = {};

이 프로젝트는 설명과 커뮤니케이션은 한국어로 진행하지만, 코드 내부의 변수명과 함수명은 영어를 사용합니다. 이는 코드의 국제적 관례를 유지하면서도 작업 설명은 한국어로 이해하기 쉽게 하기 위한 절충안입니다.

8-2. Commit Message Format

원문	설명
### 언어 규칙	제목은 “언어 규칙”이지만, 실제 내용은 커밋 메시지 형식에 가깝습니다. 블로그에서는 “커밋 메시지 규칙”으로 소개해도 좋습니다.
<code>```</code>	Markdown 코드 블록 시작입니다.
type(scope): 한국어로 작성된 커밋 메시지 제목	커밋 메시지 제목 형식입니다. Conventional Commit 스타일을 따릅니다.
빈 줄	제목과 상세 설명을 구분합니다.
한국어로 작성된 상세 설명 (선택사항)	필요하면 커밋 본문에 상세 설명을 한국어로 작성합니다.
<code>```</code>	코드 블록 종료입니다.

커밋 메시지 형식은 다음과 같습니다.

type(scope): 커밋 제목

상세 설명

예시:

feat(impl): 할 일 추가 기능 구현

사용자가 입력한 할 일을 목록에 추가할 수 있도록 TodoForm 컴포넌트를 구현했습니다.

구성 요소는 다음과 같습니다.

요소	의미
type	작업 종류
scope	작업 범위
:	type/scope와 제목을 구분
커밋 제목	어떤 변경이 있었는지 한 줄로 요약
상세 설명	선택 사항

8-3. AI 응답 메시지 언어

원문	설명
AI응답 메시지 언어: 한국어	AI가 사용자에게 답변할 때는 한국어를 사용해야 한다는 규칙입니다.
코드 식별자 언어: 영어	코드 안의 변수명, 함수명, 타입명 등은 영어로 작성합니다.
파일/폴더/브랜치 이름 언어: 영어	파일명, 폴더명, Git 브랜치명은 영어로 작성합니다.

이 규칙은 앞의 Language Rules를 다시 한번 요약한 것입니다.

예를 들어 브랜치명은 다음처럼 작성합니다.

feature/todo-list
fix/dark-mode-toggle
docs/project-structure

한국어 브랜치명은 피합니다.

기능/할일목록
수정/다크모드

8-4. Commit Types

원문	설명
Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`	커밋 타입으로 사용할 수 있는 값들을 정의합니다.

각 타입의 의미는 다음과 같습니다.

타입	의미	예시
feat	새로운 기능 추가	Todo 추가 기능 구현
fix	버그 수정	다크 모드 토글 오류 수정
docs	문서 수정	README 업데이트
refactor	기능 변화 없는 코드 구조 개선	컴포넌트 분리
test	테스트 코드 추가/수정	TodoForm 테스트 추가
chore	설정, 빌드, 패키지 등 기타 작업	ESLint 설정 변경

예시:

feat(impl): 할 일 추가 기능 구현
fix(task): 완료 상태 토글 오류 수정
docs(spec): 프로젝트 구조 문서화

8-5. Commit Scopes

원문	설명
Scopes: `const`, `spec`, `plan`, `task`, `impl`	커밋의 작업 범위를 나타내는 scope 목록입니다.

각 scope는 프로젝트 작업 단계를 나타내는 용도로 볼 수 있습니다.

Scope	의미
const	프로젝트 원칙 또는 constitution 관련 작업으로 해석 가능
spec	요구사항 명세 관련 작업
plan	구현 계획 관련 작업
task	세부 작업 목록 또는 태스크 관련 작업
impl	실제 구현 작업

예시:

docs(spec): 요구사항 명세 정리
feat(impl): 할 일 목록 UI 구현
fix(task): 작업 목록 오타 수정

type이 변경의 종류를 나타낸다면, scope는 변경이 발생한 영역을 나타냅니다. 예를 들어 feat(impl)은 “구현 영역에서 새로운 기능이 추가되었다”는 의미입니다.

8-6. Commit Examples

원문	설명
Examples:	커밋 메시지 예시를 소개합니다.
- `feat(impl): 할 일 목록 추가 기능 구현`	구현 영역에서 새로운 기능을 추가한 커밋입니다.
- `fix(task): 다크 모드 토글 버그 수정`	task 영역에서 다크 모드 토글 관련 버그를 수정한 커밋입니다.
- `docs(spec): 프로젝트 구조 문서화`	spec 영역에서 프로젝트 구조 문서를 작성하거나 수정한 커밋입니다.

각 예시를 풀어보면 다음과 같습니다.

feat(impl): 할 일 목록 추가 기능 구현

feat: 새로운 기능
impl: 실제 구현 영역
할 일 목록 추가 기능 구현: 커밋 내용 요약

fix(task): 다크 모드 토글 버그 수정

fix: 버그 수정
task: 작업 단위 또는 태스크 영역
다크 모드 토글 버그 수정: 수정 내용 요약

docs(spec): 프로젝트 구조 문서화

docs: 문서 작업
spec: 명세 영역
프로젝트 구조 문서화: 문서화 내용 요약

9. Important Notes

원문	설명
## Important Notes	프로젝트 작업 시 반드시 기억해야 할 주의사항입니다.
- This is a fresh Next.js project - core todo functionality not yet implemented	이 프로젝트는 새로 생성된 Next.js 프로젝트이며, 핵심 Todo 기능은 아직 구현되지 않았다는 뜻입니다.
- React Compiler is enabled - trust automatic optimizations	React Compiler가 활성화되어 있으므로 자동 최적화를 신뢰하라는 의미입니다.
- Tailwind v4 syntax differs from v3 (note the @import and @theme directives)	Tailwind v4 문법은 v3와 다르므로 @import, @theme 지시어를 주의해야 합니다.
- TypeScript strict mode requires explicit type handling	TypeScript strict mode에서는 타입 처리를 명확하게 해야 합니다.

이 섹션은 AI에게 “실수하기 쉬운 지점”을 알려주는 역할을 합니다.

특히 중요한 주의사항은 다음입니다.

아직 Todo 기능은 구현되지 않음

core todo functionality not yet implemented

즉, 현재는 프로젝트 초기 상태입니다.
AI가 “이미 Todo 기능이 있다”고 가정하면 안 됩니다.

React Compiler 활성화

React Compiler is enabled

따라서 과도한 수동 최적화를 피해야 합니다.

Tailwind v4 문법 주의

@import "tailwindcss";
@theme inline {
  ...
}

Tailwind v3 방식과 다르기 때문에 AI가 예전 문법을 생성하지 않도록 주의시킵니다.

TypeScript strict mode

strict mode requires explicit type handling

null, undefined, props type, event type 등을 명확하게 처리해야 합니다.

요약 문단

copilot-instructions.md는 GitHub Copilot이나 AI Agent가 프로젝트의 개발 규칙을 이해하도록 돕는 지침 파일입니다. 이 문서에는 프로젝트의 기술 스택, 폴더 구조, 실행 명령어, 컴포넌트 작성 방식, Tailwind CSS 스타일링 규칙, TypeScript 설정, React Compiler 사용 원칙, 폰트 관리 방식, ESLint 설정, 새 기능 추가 방식, 커밋 메시지 규칙 등이 정리되어 있습니다.

특히 이 프로젝트는 Next.js 16 App Router, React 19, TypeScript strict mode, Tailwind CSS v4를 사용하기 때문에 AI가 예전 방식의 코드를 생성하지 않도록 명확한 기준을 제공합니다. 또한 모든 AI 응답은 한국어로 작성하고, 코드 식별자와 파일명은 영어로 작성하도록 규칙을 분리하여 협업 시 일관성을 유지합니다.

결국 이 파일의 목적은 단순한 문서화가 아니라, AI가 프로젝트의 맥락을 이해하고 일관된 방식으로 코드를 작성하도록 만드는 것입니다.

전체 구조 요약

섹션	역할
Project Overview	프로젝트의 전체 개요 설명
Tech Stack	사용 기술과 버전 정리
Project Structure	주요 폴더와 파일 구조 설명
Development Commands	개발, 빌드, 실행, 검사 명령어 정리
Key Conventions	컴포넌트, 스타일, TypeScript, React Compiler, 폰트, ESLint 규칙
Adding New Features	새 페이지, Client Component, 스타일 추가 방식
Communication & Commit Conventions	언어 규칙과 커밋 메시지 규칙
Important Notes	프로젝트 작업 시 주의해야 할 핵심 사항

이 파일의 핵심 가치

copilot-instructions.md의 가장 큰 장점은 AI에게 다음 정보를 명확히 전달한다는 점입니다.

이 프로젝트는 어떤 기술을 쓰는가?
어떤 구조를 따르는가?
어떤 코드 스타일을 선호하는가?
어떤 문법을 사용해야 하는가?
어떤 방식으로 설명하고 커밋해야 하는가?
무엇을 조심해야 하는가?

따라서 이 파일은 단순한 README가 아니라, AI 협업을 위한 프로젝트 운영 규칙서에 가깝습니다.

저작자표시 비영리 변경금지 (새창열림)

'AI Native > Github Spec Kit으로 구현하는 SDD v1' 카테고리의 다른 글

.specify/memory/constitution.md (0)	2026.05.13
Lab 03: 신규 기능을 위한 완전한 Spec Driven Development 사이클 (0)	2026.05.13
Lab 02: GitHub Spec Kit을 활용한 Spec Driven Development (0)	2026.05.13
Lab 01: Next.js 프로젝트에 테스트 환경 설정하기 (0)	2026.05.13
Lab 00: 로컬 Git 리포(todolist-app) → GitHub 원격(SSH) → feature 개발 → PR → merge → 로컬 동기화 (0)	2026.05.13

copilot-instructions.md