feat(content): 글 형식 audit와 LLM Wiki 구축기 추가 (#111)

* fix(blog): 조회수와 콘텐츠 로깅 안정화

빌드 중 Supabase 조회수 집계 쿼리를 건너뛰어 production build 재현성을 높였습니다.

콘텐츠 로딩과 조회수 실패 로그는 민감한 경로나 원본 오류를 직접 노출하지 않도록 정리했습니다.
ViewCounter의 sessionStorage 접근과 Mermaid 보안 설정도 함께 보강했습니다.

* feat(content): 글 형식과 성장 audit 추가

category와 contentType을 분리하고 기존 글 meta에 형식 분류를 부여했습니다.

qualityReview에 글쓰기 점수 축을 확장하고 content:audit, new-post scaffold, repo-local blog-growth-review skill을 추가했습니다.

점수는 v1에서 공개 UI에 노출하지 않고 작성과 리뷰 운영 도구로만 사용합니다.

* chore(content): 글쓰기 점수 초기 채점

blog-growth-review 기준으로 공개 글과 private 시리즈 글의 writing score를 초기 채점했습니다.

기존 core qualityReview 값은 보존하고 clarity, structure, evidence, usefulness, originality, polish만 채웠습니다.
content:audit 기준 writing score coverage를 41/41로 맞췄습니다.

* feat(seo): 검색 노출 metadata 보강

검색엔진이 대표 URL을 명확히 해석할 수 있도록 canonical, og:url, 게시글별 Twitter metadata를 추가했습니다.

sitemap에 공개 허브 라우트를 포함하고 post updated 값을 lastModified에 반영하도록 조정했습니다.

* docs(blog): LLM Wiki 구축기 추가

raw, drafts, wiki 신뢰 경계를 중심으로 LLM Wiki 구축 회고 글을 추가했습니다.

로컬에서 private 글을 미리보기할 수 있도록 development preview 정책과 ADR을 추가하고 Playwright 임시 파일을 ignore 처리했습니다.

* fix(content): PR 리뷰 정책 오류 수정

contentType을 ingestion 필수 필드로 바꾸고 production build에서도 콘텐츠 진단 로그가 남도록 수정했습니다.

Life 글의 writing score 부족은 private 전환 검토가 아니라 보강 필요로 분류하도록 audit 정책과 테스트를 보강했습니다.

* fix(blog): 본문 문단 typography 적용 수정

Author: dev-wooyeon

.agents/skills/blog-growth-review/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: blog-growth-review
+description: Review and score Ark blog posts in this repository. Use when evaluating a post draft or published post for contentType classification, writing quality scores, publication readiness, improvement priorities, or when proposing meta.json qualityReview updates for posts/**/index.mdx and posts/**/meta.json.
+---
+
+# Blog Growth Review
+
+## Workflow
+
+1. Read `docs/blog-quality-guide.md`, the target `index.mdx`, and its sibling
+   `meta.json` before judging the post.
+2. Preserve `category: Tech | Life`; classify the writing form with
+   `contentType: essay | retrospective | review`.
+3. Score only for authoring/review operations. Do not expose scores in public UI
+   unless the user explicitly asks for a UI change.
+4. Return a scorecard, publication verdict, and focused improvement checklist.
+   Do not edit files unless the user asks for implementation.
+
+## contentType Rules
+
+- `essay`: opinion, argument, personal interpretation, principle, or explanatory
+  guide.
+- `retrospective`: event or project review with context, turning points, lessons,
+  and next actions.
+- `review`: evaluation of an external object or experience such as a book, trip,
+  product, article, or venue.
+
+If multiple types fit, choose the reader expectation that dominates the title and
+opening section. Keep technical project writeups as `retrospective` when the
+article is organized around a concrete build, incident, migration, or work
+outcome.
+
+## Scorecard
+
+Use 1-5 scores in 0.5 increments. Use `null` only when the source is not
+available enough to judge.
+
+- `philosophy`: reusable judgment, principle, or decision quality.
+- `design`: structure, flow, framing, and section architecture.
+- `implementation`: concrete execution detail, examples, evidence, or mechanism.
+- `brandFit`: fit with Ark's public identity and author positioning.
+- `clarity`: clear thesis, terms, conclusion, and reader promise.
+- `structure`: narrative progression and section-level cohesion.
+- `evidence`: concrete scenes, data, examples, constraints, or references.
+- `usefulness`: reader takeaway, applicability, and decision support.
+- `originality`: author's perspective beyond generic summary.
+- `polish`: sentence quality, duplication removal, tone consistency, and typos.
+
+## Type-Specific Checks
+
+- `essay`: strong point of view, controlled abstraction, enough concrete anchors,
+  and a final reusable thought.
+- `retrospective`: timeline or situation, decision point, failure or tradeoff,
+  changed behavior, and next-time rule.
+- `review`: evaluation criteria, who should care, what worked or did not, and a
+  recommendation boundary.
+
+## Output Format
+
+Return:
+
+````markdown
+## Verdict
+- contentType: ...
+- publication: 공개 유지 | 보강 필요 | private 전환 검토
+- summary: ...
+
+## Scorecard
+| Axis | Score | Reason |
+| --- | ---: | --- |
+
+## Improvements
+1. ...
+2. ...
+3. ...
+
+## Suggested meta.json patch
+```json
+{
+  "contentType": "...",
+  "qualityReview": {
+    "...": "..."
+  }
+}
+```
+````
+
+Omit the suggested patch when the user asked only for conceptual feedback.

.agents/skills/blog-growth-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Blog Growth Review"
+  short_description: "Score and review Ark blog posts"
+  default_prompt: "Review this blog post for content type, quality scores, publication readiness, and concrete improvements."

.gitignore

@@ -41,4 +41,5 @@ next-env.d.ts
 .husky/
 .sisyphus/
 .claude/
+.playwright-cli/
 .idea

app/page.tsx

@@ -1 +1,22 @@
+import type { Metadata } from 'next';
+import { SITE_DESCRIPTION, SITE_NAME, createSiteUrl } from '@/site/config/site';
+
+const homeUrl = createSiteUrl();
+
+export const metadata: Metadata = {
+  alternates: {
+    canonical: homeUrl,
+  },
+  openGraph: {
+    title: SITE_NAME,
+    description: SITE_DESCRIPTION,
+    url: homeUrl,
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: SITE_NAME,
+    description: SITE_DESCRIPTION,
+  },
+};
+
 export { default } from '@/site/home/ui/pages/HomePage';

app/sitemap.test.ts

@@ -21,4 +21,36 @@ describe('sitemap', () => {
       );
     }
   });
+
+  it('includes public hub routes for discovery', () => {
+    const entries = sitemap();
+    const urls = entries.map((entry) => entry.url);
+
+    expect(urls).toEqual(
+      expect.arrayContaining([
+        SITE_URL,
+        `${SITE_URL}/blog`,
+        `${SITE_URL}/engineering`,
+        `${SITE_URL}/life`,
+        `${SITE_URL}/series`,
+        `${SITE_URL}/resume`,
+        `${SITE_URL}/rss.xml`,
+      ])
+    );
+  });
+
+  it('uses updated date for post lastModified when available', () => {
+    const entries = sitemap();
+    const publicUpdatedPost = getSortedFeedData().find((post) => post.updated);
+
+    if (!publicUpdatedPost) {
+      return;
+    }
+
+    expect(
+      entries.find(
+        (entry) => entry.url === `${SITE_URL}/blog/${publicUpdatedPost.slug}`
+      )?.lastModified
+    ).toBe(publicUpdatedPost.updated);
+  });
 });

app/sitemap.ts

@@ -1,26 +1,48 @@
 import { MetadataRoute } from 'next';
+import { getSeriesSummaries } from '@/blog/model/series-group';
 import { getSortedFeedData } from '@/blog/services/post-repository';
-import { SITE_FEED_PATH, SITE_URL } from '@/site/config/site';
+import {
+  SITE_FEED_PATH,
+  createSiteUrl,
+  type SitePath,
+} from '@/site/config/site';
 
 export default function sitemap(): MetadataRoute.Sitemap {
   const feeds = getSortedFeedData();
 
   const feedEntries = feeds.map((feed) => ({
-    url: `${SITE_URL}/blog/${feed.slug}`,
-    lastModified: feed.date, // Use actual post date
+    url: createSiteUrl(`/blog/${feed.slug}`),
+    lastModified: feed.updated ?? feed.date,
     changeFrequency: 'weekly' as const,
     priority: 0.7,
   }));
 
-  const routes = ['', '/engineering', '/life', '/resume', SITE_FEED_PATH].map(
-    (route) => ({
-      url: `${SITE_URL}${route}`,
-      lastModified: new Date().toISOString().split('T')[0],
-      changeFrequency:
-        route === SITE_FEED_PATH ? ('daily' as const) : ('monthly' as const),
-      priority: 1,
-    })
-  );
+  const seriesEntries = getSeriesSummaries(
+    feeds.filter((feed) => feed.category === 'Tech')
+  ).map((series) => ({
+    url: createSiteUrl(`/engineering/series/${encodeURIComponent(series.id)}`),
+    lastModified: series.latestDate,
+    changeFrequency: 'weekly' as const,
+    priority: 0.6,
+  }));
+
+  const routePaths: SitePath[] = [
+    '',
+    '/blog',
+    '/engineering',
+    '/life',
+    '/series',
+    '/resume',
+    SITE_FEED_PATH,
+  ];
+
+  const routes = routePaths.map((route) => ({
+    url: createSiteUrl(route),
+    lastModified: new Date().toISOString().split('T')[0],
+    changeFrequency:
+      route === SITE_FEED_PATH ? ('daily' as const) : ('monthly' as const),
+    priority: 1,
+  }));
 
-  return [...routes, ...feedEntries];
+  return [...routes, ...seriesEntries, ...feedEntries];
 }

blog/api/view.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cookies, headers } from 'next/headers';
 import { getSupabaseServerClient } from '@/infra/integrations/supabase';
 import {
@@ -78,15 +78,31 @@ function createSupabaseMock(options: {
 const mockedGetSupabase = vi.mocked(getSupabaseServerClient);
 const mockedCookies = vi.mocked(cookies);
 const mockedHeaders = vi.mocked(headers);
+const originalNextPhase = process.env.NEXT_PHASE;
+const originalNpmLifecycleEvent = process.env.npm_lifecycle_event;
+
+function restoreBuildPhaseEnv() {
+  if (originalNextPhase === undefined) {
+    delete process.env.NEXT_PHASE;
+  } else {
+    process.env.NEXT_PHASE = originalNextPhase;
+  }
+
+  if (originalNpmLifecycleEvent === undefined) {
+    delete process.env.npm_lifecycle_event;
+  } else {
+    process.env.npm_lifecycle_event = originalNpmLifecycleEvent;
+  }
+}
 
-function createCookieStoreMock(visitorId: string | null = null): CookieStoreLike {
+function createCookieStoreMock(
+  visitorId: string | null = null
+): CookieStoreLike {
   return {
     get: vi
       .fn()
       .mockReturnValue(
-        visitorId
-          ? { name: 'view_visitor_id', value: visitorId }
-          : null
+        visitorId ? { name: 'view_visitor_id', value: visitorId } : null
       ),
     set: vi.fn(),
   };
@@ -102,6 +118,7 @@ function createHeaderStoreMock(
 
 describe('view actions', () => {
   beforeEach(() => {
+    restoreBuildPhaseEnv();
     vi.clearAllMocks();
     mockedCookies.mockResolvedValue(createCookieStoreMock());
     mockedHeaders.mockResolvedValue(
@@ -113,6 +130,10 @@ describe('view actions', () => {
     );
   });
 
+  afterEach(() => {
+    restoreBuildPhaseEnv();
+  });
+
   it('increments view when slug is valid and client exists', async () => {
     const client = createSupabaseMock({
       queryPayload: { data: { count: 10 }, error: null },
@@ -254,6 +275,29 @@ describe('view actions', () => {
     );
   });
 
+  it('uses standard client hints platform header for fingerprinting', async () => {
+    const client = createSupabaseMock({
+      queryPayload: { data: { count: 1 }, error: null },
+      rpcPayload: { data: 5, error: null },
+    });
+    const headerStore = createHeaderStoreMock({
+      'x-forwarded-for': '203.0.113.10',
+      'user-agent': 'Vitest Browser',
+      'accept-language': 'ko-KR',
+      'sec-ch-ua': '"Chromium";v="126"',
+      'sec-ch-ua-platform': '"macOS"',
+    });
+    mockedGetSupabase.mockReturnValue(client);
+    mockedHeaders.mockResolvedValue(headerStore);
+
+    await trackView('my-post');
+
+    expect(headerStore.get).toHaveBeenCalledWith('sec-ch-ua-platform');
+    expect(headerStore.get).not.toHaveBeenCalledWith(
+      'sec-ch-ua-infrastructure'
+    );
+  });
+
   it('falls back to legacy increment signature when rpc argument mismatch occurs', async () => {
     const client = {
       from: vi.fn().mockReturnValue({
@@ -379,6 +423,24 @@ describe('view actions', () => {
     expect(result).toEqual([]);
   });
 
+  it('skips popular query during production build phase', async () => {
+    process.env.NEXT_PHASE = 'phase-production-build';
+    mockedGetSupabase.mockReturnValue(
+      createSupabaseMock({
+        queryPayload: {
+          data: [{ slug: 'a', count: 10, updated_at: '2026-03-05' }],
+          error: null,
+        },
+        rpcPayload: { data: 0, error: null },
+      })
+    );
+
+    const result = await getPopularViewsInRecentDays(30, 5);
+
+    expect(result).toEqual([]);
+    expect(mockedGetSupabase).not.toHaveBeenCalled();
+  });
+
   it('normalizes invalid day/limit inputs for popular query', async () => {
     const client = createSupabaseMock({
       queryPayload: {