Agent Guide (Project-Wide)

This guide standardizes how AI coding agents (and contributors) should work in this repository. It applies to the entire repo. If a more deeply nested

AGENTS.md

appears, it takes precedence for files under its directory.

Environment & Tooling

Node:
```
22.x
```
(see
```
package.json:engines
```
)
Package manager:
```
pnpm
```
Framework: SvelteKit 2.x (Svelte 4)
Styling: Tailwind CSS (+ typography)
Markdown: mdsvex
Adapter:
```
@sveltejs/adapter-vercel
```
Tests: Vitest (+ JSDOM)

If needed locally, copy environment variables:

.env.example

→

.env

Core Commands

```
pnpm dev
```
– Start development server
```
pnpm build
```
– Production build (runs image copy step first)
```
pnpm preview
```
– Preview production build
```
pnpm check
```
/
```
pnpm check:watch
```
– Svelte/TS type checking
```
pnpm lint
```
– ESLint + Prettier check
```
pnpm format
```
– Prettier write

pnpm test

pnpm test:run

pnpm test:coverage

pnpm test:ui

– Tests

```
pnpm post
```
– Create a new blog post from template
```
pnpm seo:validate
```
– Run SEO validation checks
```
pnpm analyze
```
– Bundle analysis (client output)
```
npx vercel build
```
– Verify Vercel deployment compatibility (recommended before deploy)

Pre‑Commit / Pre‑PR Checklist

Always ensure the following pass before committing or opening a PR:

Clean build:
```
pnpm build
```
Lint/format:
```
pnpm format
```
if needed, then
```
pnpm lint
```
Type check:
```
pnpm check
```
Tests:
```
pnpm test:run
```
(when relevant changes are made)
Vercel compatibility (recommended):
```
npx vercel build
```

Run SEO validation (

pnpm seo:validate

) when:

Adding or restructuring routes/pages
Changing meta tags or structured data
Before significant releases or template/layout changes

Architecture & Structure

```
posts/
```
– Markdown posts (frontmatter-supported)
```
templates/post.md
```
– New-post template
```
scripts/create-post.ts
```
– Interactive post generator (
```
pnpm post
```
)
```
src/routes/
```
– SvelteKit routes (includes RSS and sitemap endpoints)
```
src/lib/components/
```
– Reusable Svelte components
```
src/lib/utils/
```
– Utilities (slug normalization, date, caching, URL helpers, etc.)
Static generation with prerendering enabled
RSS and sitemap generation under
```
src/routes/*/+server.*
```

Notable utilities/components:

Post utilities:
```
src/lib/utils/posts.ts
```

Date & URL helpers:

src/lib/utils/date.ts

src/lib/utils/url-helpers.ts

Caching:

src/lib/utils/cache-manager.ts

src/lib/utils/ttl-cache.ts

UI building blocks under
```
src/lib/components/ui/*
```

Content Authoring Runbook

Primary flow (interactive):

Run
```
pnpm post
```
Provide: title, slug (optional; auto-suggested), category, tags
The script writes a new file to
```
posts/
```
using
```
templates/post.md
```

Details:

Categories are defined in
```
src/lib/types/blog.ts
```
(
```
Category
```
enum). Values are Korean:
```
일상
```
(Daily),
```
개발
```
(Development),
```
생각
```
(Thoughts),
```
리뷰
```
(Review).
Slug generation is handled in
```
scripts/create-post.ts
```
and will auto-suggest; it sanitizes input and falls back to a date-time-based slug when necessary, preserving Korean where applicable.
Do not manually edit computed fields (e.g., reading time or preview) if the pipeline populates them.
Frontmatter should include at minimum:
```
title
```
,
```
description
```
,
```
date
```
,
```
category
```
, and
```
tags
```
. Optional fields include
```
updated
```
,
```
draft
```
,
```
image
```
,
```
author
```
.

Images:

See
```
docs/IMAGE_GUIDELINES.md
```
for conventions.
The build runs
```
scripts/copy-images.js
```
; other optimization scripts are available under
```
scripts/
```
if needed.

SEO & Quality

Use
```
pnpm seo:validate
```
during structural/SEO-related changes.
Ensure pages expose consistent metadata; verify RSS (
```
src/routes/rss.xml/+server.js
```
) and sitemap (
```
src/routes/sitemap.xml/+server.js
```
) still work after routing/content changes.
Keep accessible markup; see
```
src/lib/utils/accessibility.ts
```
and component patterns.

Agent Working Rules

Keep changes minimal and tightly scoped to the request.
Do not add dependencies or alter build/config unless explicitly requested.
Follow existing patterns and code style; prefer small, surgical patches.
Ensure linting, type checks, build, and relevant tests pass before proposing completion.
Update related docs when changing scripts, commands, or notable behavior.
Do not commit/push unless asked. Provide diffs/patches for review.

Testing Notes

Use Vitest for unit tests. Existing examples live under
```
src/**/**/*.test.*
```
.
When adding tests, mirror existing test structure and utilities (e.g.,
```
src/test/setup.ts
```
).
Prefer targeted tests close to the code you change.

Deployment Notes

Target is Vercel via
```
@sveltejs/adapter-vercel
```
.
Use
```
npx vercel build
```
locally to catch adapter/runtime issues before merging.
Analytics and performance tooling:
```
@vercel/analytics
```
,
```
@vercel/speed-insights
```
are integrated.

Quick Reference

Dev:
```
pnpm dev
```
Build/Preview:
```
pnpm build
```
→
```
pnpm preview
```
Lint/Format:
```
pnpm lint
```
/
```
pnpm format
```
Type check:
```
pnpm check
```
Tests:
```
pnpm test:run
```
New post:
```
pnpm post
```
SEO:
```
pnpm seo:validate
```
Vercel check:
```
npx vercel build
```

Agent Guide (Project-Wide)

This guide standardizes how AI coding agents (and contributors) should work in this repository. It applies to the entire repo. If a more deeply nested

AGENTS.md

appears, it takes precedence for files under its directory.

Environment & Tooling

Node:
```
22.x
```
(see
```
package.json:engines
```
)
Package manager:
```
pnpm
```
Framework: SvelteKit 2.x (Svelte 4)
Styling: Tailwind CSS (+ typography)
Markdown: mdsvex
Adapter:
```
@sveltejs/adapter-vercel
```
Tests: Vitest (+ JSDOM)

If needed locally, copy environment variables:

.env.example

→

.env

Core Commands

```
pnpm dev
```
– Start development server
```
pnpm build
```
– Production build (runs image copy step first)
```
pnpm preview
```
– Preview production build
```
pnpm check
```
/
```
pnpm check:watch
```
– Svelte/TS type checking
```
pnpm lint
```
– ESLint + Prettier check
```
pnpm format
```
– Prettier write

pnpm test

pnpm test:run

pnpm test:coverage

pnpm test:ui

– Tests

```
pnpm post
```
– Create a new blog post from template
```
pnpm seo:validate
```
– Run SEO validation checks
```
pnpm analyze
```
– Bundle analysis (client output)
```
npx vercel build
```
– Verify Vercel deployment compatibility (recommended before deploy)

Pre‑Commit / Pre‑PR Checklist

Always ensure the following pass before committing or opening a PR:

Clean build:
```
pnpm build
```
Lint/format:
```
pnpm format
```
if needed, then
```
pnpm lint
```
Type check:
```
pnpm check
```
Tests:
```
pnpm test:run
```
(when relevant changes are made)
Vercel compatibility (recommended):
```
npx vercel build
```

Run SEO validation (

pnpm seo:validate

) when:

Adding or restructuring routes/pages
Changing meta tags or structured data
Before significant releases or template/layout changes

Architecture & Structure

```
posts/
```
– Markdown posts (frontmatter-supported)
```
templates/post.md
```
– New-post template
```
scripts/create-post.ts
```
– Interactive post generator (
```
pnpm post
```
)
```
src/routes/
```
– SvelteKit routes (includes RSS and sitemap endpoints)
```
src/lib/components/
```
– Reusable Svelte components
```
src/lib/utils/
```
– Utilities (slug normalization, date, caching, URL helpers, etc.)
Static generation with prerendering enabled
RSS and sitemap generation under
```
src/routes/*/+server.*
```

Notable utilities/components:

Post utilities:
```
src/lib/utils/posts.ts
```

Date & URL helpers:

src/lib/utils/date.ts

src/lib/utils/url-helpers.ts

Caching:

src/lib/utils/cache-manager.ts

src/lib/utils/ttl-cache.ts

UI building blocks under
```
src/lib/components/ui/*
```

Content Authoring Runbook

Primary flow (interactive):

Run
```
pnpm post
```
Provide: title, slug (optional; auto-suggested), category, tags
The script writes a new file to
```
posts/
```
using
```
templates/post.md
```

Details:

Categories are defined in
```
src/lib/types/blog.ts
```
(
```
Category
```
enum). Values are Korean:
```
일상
```
(Daily),
```
개발
```
(Development),
```
생각
```
(Thoughts),
```
리뷰
```
(Review).
Slug generation is handled in
```
scripts/create-post.ts
```
and will auto-suggest; it sanitizes input and falls back to a date-time-based slug when necessary, preserving Korean where applicable.
Do not manually edit computed fields (e.g., reading time or preview) if the pipeline populates them.
Frontmatter should include at minimum:
```
title
```
,
```
description
```
,
```
date
```
,
```
category
```
, and
```
tags
```
. Optional fields include
```
updated
```
,
```
draft
```
,
```
image
```
,
```
author
```
.

Images:

See
```
docs/IMAGE_GUIDELINES.md
```
for conventions.
The build runs
```
scripts/copy-images.js
```
; other optimization scripts are available under
```
scripts/
```
if needed.

SEO & Quality

Use
```
pnpm seo:validate
```
during structural/SEO-related changes.
Ensure pages expose consistent metadata; verify RSS (
```
src/routes/rss.xml/+server.js
```
) and sitemap (
```
src/routes/sitemap.xml/+server.js
```
) still work after routing/content changes.
Keep accessible markup; see
```
src/lib/utils/accessibility.ts
```
and component patterns.

Agent Working Rules

Keep changes minimal and tightly scoped to the request.
Do not add dependencies or alter build/config unless explicitly requested.
Follow existing patterns and code style; prefer small, surgical patches.
Ensure linting, type checks, build, and relevant tests pass before proposing completion.
Update related docs when changing scripts, commands, or notable behavior.
Do not commit/push unless asked. Provide diffs/patches for review.

Testing Notes

Use Vitest for unit tests. Existing examples live under
```
src/**/**/*.test.*
```
.
When adding tests, mirror existing test structure and utilities (e.g.,
```
src/test/setup.ts
```
).
Prefer targeted tests close to the code you change.

Deployment Notes

Target is Vercel via
```
@sveltejs/adapter-vercel
```
.
Use
```
npx vercel build
```
locally to catch adapter/runtime issues before merging.
Analytics and performance tooling:
```
@vercel/analytics
```
,
```
@vercel/speed-insights
```
are integrated.

Quick Reference

Dev:
```
pnpm dev
```
Build/Preview:
```
pnpm build
```
→
```
pnpm preview
```
Lint/Format:
```
pnpm lint
```
/
```
pnpm format
```
Type check:
```
pnpm check
```
Tests:
```
pnpm test:run
```
New post:
```
pnpm post
```
SEO:
```
pnpm seo:validate
```
Vercel check:
```
npx vercel build
```

Agent Guide (Project-Wide)

Agent Guide (Project-Wide)

Environment & Tooling

Core Commands

Pre‑Commit / Pre‑PR Checklist

Architecture & Structure

Content Authoring Runbook

SEO & Quality

Agent Working Rules

Testing Notes

Deployment Notes

Quick Reference

Related Skills

Markdown Converter

Nano Banana Pro

1password

Agent Guide (Project-Wide)

Environment & Tooling

Core Commands

Pre‑Commit / Pre‑PR Checklist

Architecture & Structure

Content Authoring Runbook

SEO & Quality

Agent Working Rules

Testing Notes

Deployment Notes

Quick Reference