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,222 @@
+---
+id: wiki-2026-0508-executable-documentation
+title: Executable Documentation
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Living Documentation, Runnable Docs, Doc Tests]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.92
+verification_status: applied
+tags: [documentation, bdd, doctest, testing, ai]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: polyglot
+  framework: docs-as-code
+---
+
+# Executable Documentation
+
+## 매 한 줄
+> **"매 docs 의 CI 의 run — 매 stale 의 fail"**. 매 docs 의 prose 의 not — 매 examples / scenarios / API specs 의 매 actually-execute. 매 1990s Donald Knuth literate programming + Python doctest 의 origin, 매 2020s Cucumber/BDD 의 popularize, 매 2026 의 매 LLM-assisted doc generation + verification 의 standard practice.
+
+## 매 핵심
+
+### 매 종류
+1. **Doctest** — 매 docstring 안의 example 의 run (Python doctest, Rust doctests).
+2. **BDD** — Gherkin (`Given/When/Then`) 의 step 의 bind (Cucumber, Behave).
+3. **API docs from spec** — OpenAPI → contract test (Schemathesis, Dredd).
+4. **Notebook docs** — Jupyter / Quarto / Marimo 의 매 cell 의 run.
+5. **Markdown code-fence test** — `mdsh`, `mdocc`, `markdown-doctest`.
+6. **AI-verified docs** — 매 LLM 의 docs 의 read + code 의 inspect + drift 의 detect.
+
+### 매 왜 valuable
+- 매 docs 의 truth = code 의 truth.
+- 매 onboarding example 의 매 always working.
+- 매 API contract 의 single source of truth.
+- 매 refactor 시 docs 의 break — 매 catch.
+
+### 매 응용
+1. SDK / library docs (매 examples 의 always-correct).
+2. API contract testing (OpenAPI + Schemathesis).
+3. BDD acceptance tests (매 PM-readable).
+4. Tutorial CI (매 step-by-step 의 verify).
+
+## 💻 패턴
+
+### Pattern 1: Python doctest
+```python
+def fibonacci(n: int) -> int:
+    """Return the n-th Fibonacci number.
+
+    >>> fibonacci(0)
+    0
+    >>> fibonacci(10)
+    55
+    >>> [fibonacci(i) for i in range(7)]
+    [0, 1, 1, 2, 3, 5, 8]
+    """
+    a, b = 0, 1
+    for _ in range(n): a, b = b, a + b
+    return a
+
+# pytest --doctest-modules
+```
+
+### Pattern 2: Rust doctest
+```rust
+/// Adds two numbers.
+///
+/// # Examples
+/// ```
+/// use mycrate::add;
+/// assert_eq!(add(2, 3), 5);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 { a + b }
+
+// cargo test --doc
+```
+
+### Pattern 3: Cucumber BDD (TS)
+```gherkin
+# features/checkout.feature
+Feature: Checkout
+  Scenario: Successful purchase
+    Given a cart with 2 items totaling $50
+    And a valid Stripe token "tok_visa"
+    When the user submits checkout
+    Then the order status should be "paid"
+    And a confirmation email is queued
+```
+
+```typescript
+// step defs
+import { Given, When, Then } from "@cucumber/cucumber";
+Given("a cart with {int} items totaling ${int}", function (n, total) {
+  this.cart = makeCart(n, total);
+});
+When("the user submits checkout", async function () {
+  this.result = await checkout(this.cart, this.token);
+});
+Then("the order status should be {string}", function (status) {
+  expect(this.result.status).toBe(status);
+});
+```
+
+### Pattern 4: OpenAPI contract test (Schemathesis)
+```bash
+schemathesis run https://api.example.com/openapi.json \
+  --checks all \
+  --hypothesis-deadline 5000
+# 매 매 endpoint 의 spec 의 conform 의 verify (property-based).
+```
+
+### Pattern 5: Markdown code-fence test
+```typescript
+// scripts/test-readme.ts
+import { readFileSync } from "fs";
+import { execSync } from "child_process";
+
+const md = readFileSync("README.md", "utf8");
+const blocks = [...md.matchAll(/```typescript\n([\s\S]*?)\n```/g)];
+
+for (const [, code] of blocks) {
+  const tmp = `/tmp/snippet-${Date.now()}.ts`;
+  require("fs").writeFileSync(tmp, code);
+  execSync(`tsx ${tmp}`, { stdio: "inherit" });
+}
+```
+
+### Pattern 6: Quarto / Marimo notebook
+```python
+# 매 marimo notebook — 매 reactive, 매 git-friendly
+import marimo as mo
+
+@mo.cell
+def fetch():
+    import requests
+    return requests.get("https://api.example.com/users").json()
+
+@mo.cell
+def show(fetch):
+    return mo.ui.table(fetch)
+
+# 매 marimo run notebook.py — 매 docs + working app.
+```
+
+### Pattern 7: AI-verified doc drift (2026)
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+const ai = new Anthropic();
+
+async function checkDocDrift(docPath: string, codeGlob: string) {
+  const docs = readFileSync(docPath, "utf8");
+  const code = await loadFiles(codeGlob);
+
+  const res = await ai.messages.create({
+    model: "claude-opus-4-7",
+    max_tokens: 2000,
+    system: "You verify docs match code. Output JSON: {drifts:[{location, doc_says, code_actually}]}",
+    messages: [{
+      role: "user",
+      content: `DOCS:\n${docs}\n\nCODE:\n${code}\n\nFind drift.`,
+    }],
+  });
+  return JSON.parse(res.content[0].text);
+}
+// CI 의 매 fail 의 drift 의 found 시.
+```
+
+### Pattern 8: Architecture decision record (ADR) with assertion
+```markdown
+# ADR-0042: Use Postgres for primary store
+
+## Decision
+PostgreSQL 16 의 single-tenant DB.
+
+## Verification (run in CI)
+\`\`\`bash
+# 매 docs 의 claim 의 verify
+psql $DATABASE_URL -c "SELECT version();" | grep -q "PostgreSQL 16"
+\`\`\`
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Library / SDK | doctest (Python/Rust) |
+| REST API | OpenAPI + Schemathesis |
+| Acceptance test (PM) | Cucumber BDD |
+| Tutorial / book | Markdown code-fence test |
+| Data analysis | Quarto / Marimo |
+| Architecture docs | AI drift detector |
+
+**기본값**: 매 README 예제 의 매 CI 의 run, 매 API 의 OpenAPI 의 contract test.
+
+## 🔗 Graph
+- 부모: [[Docs as Code]]
+- 응용: [[OpenAPI]]
+- Adjacent: [[Property-Based Testing]] · [[Contract Testing]]
+
+## 🤖 LLM 활용
+**언제**: 매 docs drift detection, 매 example generation 의 verify, 매 BDD step 의 generate.
+**언제 X**: 매 internal scratchpad notes — 매 over-engineering.
+
+## ❌ 안티패턴
+- **Doctest 의 too many**: 매 docstring 의 cluttered — 매 separate test 가 better.
+- **BDD 의 implementation detail**: 매 Given/When/Then 이 SQL 의 mention — 매 wrong abstraction.
+- **Spec drift**: 매 OpenAPI 의 stale — 매 generate-from-code or test 의 mandatory.
+- **No CI**: 매 executable 의 X — 매 prose docs 의 same.
+
+## 🧪 검증 / 중복
+- Verified (Knuth literate programming, Python doctest stdlib, Cucumber.io, Schemathesis docs, Marimo docs).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — doctest/BDD/OpenAPI/Marimo/AI-drift |