|
1 | | -# PROJECT KNOWLEDGE BASE |
2 | | - |
3 | | -**Generated:** 2026-02-27 |
4 | | -**Commit:** 2669f50 |
5 | | -**Branch:** master |
6 | | - |
7 | | -## OVERVIEW |
8 | | - |
9 | | -Modern tech blog platform built on Next.js App Router with MDX-based content, interactive visualization components, analytics tracking, and a token-driven design system. |
10 | | - |
11 | | -## STRUCTURE |
12 | | - |
13 | | -``` |
14 | | -eunu.log/ |
15 | | -├── src/ # Source code |
16 | | -│ ├── app/ # Next.js App Router pages |
17 | | -│ ├── core/ # App config/provider composition |
18 | | -│ ├── domains/ # Cross-feature domain contracts/schema |
19 | | -│ ├── features/ # Feature domains (blog/resume/search/home) |
20 | | -│ ├── shared/ # Shared modules (analytics/layout/ui/providers/seo/types) |
21 | | -│ ├── components/ # Visualization-heavy components |
22 | | -│ ├── styles/ # Design tokens and global styles |
23 | | -│ └── (co-located tests + shared/testing helpers) |
24 | | -├── tests/ # Centralized e2e tests (Playwright) |
25 | | -├── internal/ # Internal scripts and linting configuration |
26 | | -├── posts/ # Blog posts (MDX + metadata) |
27 | | -├── public/ # Static assets |
28 | | -├── docs/ # Project documentation |
29 | | -└── (no .agent directory) # AI collaboration rules are documented under docs/ |
30 | | -``` |
31 | | - |
32 | | -## WHERE TO LOOK |
33 | | - |
34 | | -| Task | Location | Notes | |
35 | | -| ------------------ | ----------------- | -------------------------------------------------- | |
36 | | -| Pages & Routing | `src/app/` | Next.js App Router with static generation + handlers | |
37 | | -| Components | `src/features/`, `src/shared/`, `src/components/visualization/` | Feature-first + shared modules + visualization | |
38 | | -| Content Processing | `src/features/blog/services/` | MDX feed repository, markdown parsing | |
39 | | -| Styling | `src/styles/` | CSS variables, Tailwind integration | |
40 | | -| Blog Content | `posts/` | MDX files with separate metadata | |
41 | | -| Configuration | Root | `next.config.mjs`, `package.json`, `tsconfig.json` | |
42 | | -| Internal Tooling | `internal/` | Scripts + lint/spell config | |
43 | | - |
44 | | -## CONVENTIONS |
45 | | - |
46 | | -**Content Structure:** Each blog post uses folder structure: `posts/[slug]/index.mdx + meta.json` |
47 | | -**Component Organization:** Feature-first (`src/features`) + shared modules (`src/shared`) with index.ts exports |
48 | | -**Styling:** CSS variables + Tailwind CSS hybrid approach |
49 | | -**Visualization:** Interactive visualization components live in `src/components/visualization/` and should use client runtime when browser APIs are required |
50 | | - |
51 | | -## ANTI-PATTERNS (THIS PROJECT) |
52 | | - |
53 | | -- **NEVER** use arbitrary Tailwind values like `p-[13px]` - use standard classes only |
54 | | -- **NEVER** use raw `requestAnimationFrame` loops in React UI when framework lifecycle hooks can be used |
55 | | -- **NEVER** place visualization/animation-heavy components outside `src/components/visualization/` without clear reason |
56 | | -- **NEVER** use `any` type - use `unknown` or proper types |
57 | | -- **NEVER** ship client effects that drop below smooth interaction on mobile |
58 | | - |
59 | | -## UNIQUE STYLES |
60 | | - |
61 | | -- Dual root layout pattern (`#app-root` + `#overlay-root`) for modal management |
62 | | -- Folder-based content organization with separated metadata |
63 | | -- CSS variable-driven design system integrated with Tailwind |
64 | | -- Custom webpack MDX processing instead of Next.js built-in MDX |
65 | | - |
66 | | -## COMMANDS |
67 | | - |
68 | | -```bash |
69 | | -# Development (uses webpack flag) |
70 | | -npm run dev |
71 | | - |
72 | | -# Build (uses webpack flag) |
73 | | -npm run build |
74 | | - |
75 | | -# Testing (Vitest, not Jest) |
76 | | -npm test |
77 | | - |
78 | | -# Bundle analysis |
79 | | -ANALYZE=true npm run build |
80 | | -``` |
81 | | - |
82 | | -## NOTES |
83 | | - |
84 | | -- Uses Vitest instead of Jest for testing |
85 | | -- Uses Playwright for mobile-focused e2e coverage |
86 | | -- Webpack flag suggests Turbopack compatibility issues |
87 | | -- No CI/CD setup - relies on Vercel auto-deployment |
88 | | -- Korean language content support in feeds |
89 | | -- Current app dependencies include Next.js 16 and React 19 |
90 | | -- AI collaboration guide: `docs/guides/ai-collaboration.md` |
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Always-Follow Rules |
| 4 | +- Keep changes minimal and scoped to the task. Do not edit unrelated files. |
| 5 | +- Preserve the current MDX pipeline. MDX must stay on the custom webpack rule with `@mdx-js/loader` in `next.config.mjs`; do not switch to Next.js built-in MDX unless the whole content pipeline is intentionally migrated. |
| 6 | +- Keep visualization-heavy UI in `src/components/visualization/`. Do not move that code to other folders without a clear architectural reason. |
| 7 | +- Never use `any`. Use concrete types or `unknown` with narrowing. |
| 8 | +- Never use arbitrary Tailwind values such as `p-[13px]`. Use standard utilities, shared tokens, and existing style patterns. |
| 9 | +- Do not replace feature-first structure with flat shared folders. Keep code in `src/features/`, `src/shared/`, and `src/domains/` by responsibility. |
| 10 | +- Preserve blog content structure as `posts/**/index.mdx` with nearby `meta.json`, including nested series directories when present. |
| 11 | + |
| 12 | +## Project Structure |
| 13 | +- `src/app/` — Next.js App Router pages, layouts, handlers |
| 14 | +- `src/core/` — app-level providers and configuration composition |
| 15 | +- `src/domains/` — cross-feature contracts and schemas |
| 16 | +- `src/features/` — feature modules such as blog, home, resume, and search |
| 17 | +- `src/shared/` — reusable UI, layout, analytics, SEO, and providers |
| 18 | +- `src/components/visualization/` — animation and visualization-heavy components |
| 19 | +- `src/styles/` — design tokens and global styles |
| 20 | +- `posts/` — blog content, series entries, and metadata managed as nested `index.mdx` + `meta.json` |
| 21 | +- `tests/` — Playwright end-to-end coverage |
| 22 | +- `internal/` — scripts and tool configuration |
| 23 | + |
| 24 | +## Development Commands |
| 25 | +- `npm run dev` — run the local dev server with webpack |
| 26 | +- `npm run build` — create the production build |
| 27 | +- `npm run lint` — run ESLint on source files |
| 28 | +- `npm run lint:css:syntax` — check CSS syntax rules |
| 29 | +- `npm run test:unit` — run Vitest unit tests |
| 30 | +- `npm run test:components` — run component-focused Vitest tests |
| 31 | +- `npm run test:e2e` — run Playwright scenarios |
| 32 | +- `npm run test:ci` — run the main CI-equivalent validation set |
| 33 | + |
| 34 | +## Style & Testing |
| 35 | +Use TypeScript with 2-space indentation, semicolons, single quotes, trailing commas (`es5`), and 80-column width; Prettier enforces this. Name components in `PascalCase`, hooks in `camelCase` with a `use` prefix, and tests as `*.test.ts` or `*.test.tsx`. Add targeted Vitest or Playwright coverage when changing logic, UI behavior, parsers, or app actions. Before opening a PR, run `npm run build` and the most relevant test command for the change. |
| 36 | + |
| 37 | +## Commits & PRs |
| 38 | +Use commit messages like `type(scope): concise description`, for example `fix(home): preview 배포 타입 오류 수정`. Common types include `feat`, `fix`, `refactor`, `test`, and `chore`. Use branch names like `codex/<task>`. Follow `.github/pull_request_template.md`, link related issues or PRs, and include screenshots when UI changes are visible. Confirm mobile/desktop and dark/light behavior when layout or navigation changes. |
0 commit comments