refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조

에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 11:05:56 +09:00
parent 6549ead309
commit c24165b8bc
6193 changed files with 1717 additions and 31 deletions
@@ -0,0 +1,179 @@
+---
+id: wiki-2026-0508-incremental-static-regeneration-
+title: Incremental Static Regeneration (ISR)
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [ISR, Stale-While-Revalidate Static, On-Demand Revalidation]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [architecture, nextjs, ssg, caching, web]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: typescript
+  framework: nextjs
+---
+
+# Incremental Static Regeneration (ISR)
+
+## 매 한 줄
+> **"매 static page 의 build-time 의 prerender + runtime 의 stale-while-revalidate 의 통한 fresh 의 hybrid"**. 매 Next.js 9.5 (2020) 의 introduction, 매 Vercel 의 patent (US 11,055,090), 매 modern 의 Next.js 15 App Router 의 `revalidate` + `revalidateTag` + `revalidatePath` 의 first-class.
+
+## 매 핵심
+
+### 매 ISR 동작
+1. Build 시 page 의 prerender → static HTML + JSON.
+2. Request 의 cached HTML 의 즉시 serve.
+3. `revalidate: N` 초 후 첫 request 의 background regenerate trigger.
+4. 매 그 request 는 stale 의 받음, 매 다음 request 는 fresh.
+5. On-demand: webhook → `revalidateTag('post-123')` 의 cache 의 invalidate.
+
+### 매 ISR vs SSR vs SSG
+- **SSG**: build-time only, content change → rebuild.
+- **SSR**: every request, fresh but slow + costly.
+- **ISR**: prerendered + revalidate window, near-CDN speed + freshness.
+- **PPR (Partial Prerendering, Next.js 15)**: static shell + dynamic holes — ISR 의 evolution.
+
+### 매 응용
+1. Marketing/blog (수십만 page).
+2. E-commerce product page (price/stock 의 stale OK seconds).
+3. Docs site (authored content, low write rate).
+
+## 💻 패턴
+
+### App Router — Time-Based Revalidate
+```typescript
+// app/blog/[slug]/page.tsx
+export const revalidate = 60; // seconds
+
+export default async function Post({ params }: { params: { slug: string } }) {
+  const post = await fetch(`https://cms.example.com/posts/${params.slug}`, {
+    next: { revalidate: 60, tags: [`post:${params.slug}`] },
+  }).then(r => r.json());
+
+  return <article>{post.title}</article>;
+}
+
+export async function generateStaticParams() {
+  const posts = await fetch('https://cms.example.com/posts').then(r => r.json());
+  return posts.map((p: any) => ({ slug: p.slug }));
+}
+```
+
+### On-Demand — `revalidateTag`
+```typescript
+// app/api/revalidate/route.ts
+import { revalidateTag } from 'next/cache';
+import { NextRequest } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const secret = req.headers.get('x-webhook-secret');
+  if (secret !== process.env.WEBHOOK_SECRET) {
+    return new Response('forbidden', { status: 403 });
+  }
+  const { slug } = await req.json();
+  revalidateTag(`post:${slug}`);
+  return Response.json({ revalidated: true, slug });
+}
+```
+
+### `revalidatePath` (entire route)
+```typescript
+import { revalidatePath } from 'next/cache';
+
+export async function publishPost(slug: string) {
+  await db.posts.update({ where: { slug }, data: { published: true } });
+  revalidatePath(`/blog/${slug}`);
+  revalidatePath('/blog');
+}
+```
+
+### Pages Router (legacy `getStaticProps`)
+```typescript
+// pages/products/[id].tsx
+export async function getStaticProps({ params }) {
+  const product = await fetch(`/api/products/${params.id}`).then(r => r.json());
+  return { props: { product }, revalidate: 30 };
+}
+
+export async function getStaticPaths() {
+  const top100 = await fetch('/api/products?top=100').then(r => r.json());
+  return {
+    paths: top100.map((p: any) => ({ params: { id: p.id } })),
+    fallback: 'blocking', // first request 의 SSR-then-cache
+  };
+}
+```
+
+### CMS Webhook → ISR
+```typescript
+// Sanity / Contentful / Strapi webhook
+{
+  "url": "https://app.example.com/api/revalidate",
+  "headers": { "x-webhook-secret": "..." },
+  "events": ["entry.publish", "entry.update"]
+}
+```
+
+### Partial Prerendering (Next.js 15)
+```typescript
+// next.config.ts
+export default { experimental: { ppr: 'incremental' } };
+
+// app/page.tsx
+export const experimental_ppr = true;
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <>
+      <StaticHero />               {/* prerendered */}
+      <Suspense fallback={<Skel/>}>
+        <DynamicCart />            {/* streamed at request time */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Content-heavy, low write | ISR + on-demand revalidate |
+| Per-user dashboard | SSR / Server Components (no ISR) |
+| Pure static (마케팅 사이트) | SSG, no revalidate |
+| Real-time (stock ticker) | Streaming / WebSocket |
+| Mixed page (static + dynamic) | PPR (Next.js 15+) |
+
+**기본값**: 매 content site — App Router + tag-based on-demand revalidation, 매 fallback 의 time-based 60s.
+
+## 🔗 Graph
+- 부모: [[Web-Rendering-Strategies]]
+- 변형: [[Stale-While-Revalidate]] · [[Edge-SSR]]
+- 응용: [[Next.js]]
+- Adjacent: [[CDN]] · [[React Server Components — 경계 의식]] · [[Island Architecture]]
+
+## 🤖 LLM 활용
+**언제**: revalidate strategy 의 design, webhook handler 의 generate, cache tag 의 schema 의 propose.
+**언제 X**: 매 personalized content 의 cache key 의 design (PII leak risk — human review 필수).
+
+## ❌ 안티패턴
+- **Per-user ISR**: cookie/auth-dependent page 의 ISR → cross-user data leak.
+- **Tag explosion**: 매 query 의 unique tag → 매 cache 의 fragmentation.
+- **No fallback**: `fallback: false` + dynamic params → 404 의 surprise.
+- **Webhook 의 unsecured**: secret 의 X → revalidate 의 abuse 의 origin DoS.
+- **Long `revalidate`**: 1-day window 의 stale price → 매 revenue loss.
+
+## 🧪 검증 / 중복
+- Verified (Next.js 15 docs, Vercel ISR blog 2020-2025).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — Next.js ISR 의 full content |