docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,275 @@
|
||||
---
|
||||
id: wiki-2026-0508-be-detailed
|
||||
title: Be Detailed (Specificity Principle)
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [구체화, specificity, prompt detail, requirement specification, edge case enumeration]
|
||||
duplicate_of: none
|
||||
source_trust_level: B
|
||||
confidence_score: 0.85
|
||||
verification_status: applied
|
||||
tags: [communication, prompt-engineering, requirements, spec, detail, edge-case, anti-vague]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: communication / spec
|
||||
applicable_to: [Prompt Engineering, RFC, Spec Writing, Bug Reports]
|
||||
---
|
||||
|
||||
# Be Detailed (Specificity Principle)
|
||||
|
||||
## 📌 한 줄 통찰
|
||||
> **"매 devil 의 detail"**. 매 abstraction 의 hide X — 매 number, 매 context, 매 edge. 매 prompt engineering 의 single biggest lever — 매 vague "make it good" → 매 hallucination, 매 specific "max 50 words, 매 active voice" → 매 reliable.
|
||||
|
||||
## 📖 핵심
|
||||
|
||||
### 매 specificity tool
|
||||
|
||||
#### 1. Quantification
|
||||
- ❌ "매우 빠름"
|
||||
- ✅ "p99 < 100ms"
|
||||
- ❌ "큰 file"
|
||||
- ✅ "100MB 이상"
|
||||
|
||||
#### 2. Contextualization
|
||||
- ❌ "login button"
|
||||
- ✅ "centered modal with email + password + social OAuth (Google, Apple), max-width 400px"
|
||||
|
||||
#### 3. Edge case enumeration
|
||||
- 매 happy path 의 X.
|
||||
- 매 empty / null / overflow / unicode / negative / boundary.
|
||||
- 매 concurrent / partial failure / network split.
|
||||
|
||||
#### 4. Negative spec
|
||||
- "should NOT" 의 explicit.
|
||||
- 매 boundary 의 clarify.
|
||||
|
||||
#### 5. Acceptance criteria
|
||||
- 매 verifiable.
|
||||
- 매 Given-When-Then.
|
||||
|
||||
### 매 spec hierarchy
|
||||
|
||||
#### Vague → Specific
|
||||
1. "Make it user-friendly"
|
||||
2. "Reduce form fields"
|
||||
3. "Reduce checkout from 6 fields to 2 (email, payment)"
|
||||
4. "Reduce checkout from 6 fields to 2 (email, payment), keep address auto-fill via Stripe Address Element, A/B test 50/50 for 2 weeks"
|
||||
|
||||
→ 매 step 4 만 의 actionable.
|
||||
|
||||
### 매 prompt engineering 의 detail
|
||||
|
||||
#### 매 vague (bad)
|
||||
> "Write me a poem"
|
||||
|
||||
#### 매 specific (good)
|
||||
> "Write a 4-line haiku about autumn leaves.
|
||||
> Format: 5-7-5 syllables.
|
||||
> Tone: melancholic.
|
||||
> No rhyming required.
|
||||
> Output: poem only, no explanation."
|
||||
|
||||
→ 매 hallucination ↓, 매 reliability ↑.
|
||||
|
||||
### 매 RFC / spec format
|
||||
1. **Motivation**: 매 why.
|
||||
2. **Detailed design**: 매 how.
|
||||
3. **Drawbacks**: 매 cost.
|
||||
4. **Alternatives**: 매 other approaches.
|
||||
5. **Unresolved questions**: 매 known gap.
|
||||
6. **Future work**: 매 next.
|
||||
|
||||
### 매 bug report (specific)
|
||||
- 매 reproducer (minimum case).
|
||||
- 매 expected vs actual.
|
||||
- 매 environment (OS, browser, version).
|
||||
- 매 logs / stack trace.
|
||||
- 매 frequency (always / 50% / random).
|
||||
- 매 impact.
|
||||
|
||||
### 매 over-detail risk
|
||||
- 매 over-spec: 매 implementation 의 lock-in.
|
||||
- 매 micro-management: 매 creativity X.
|
||||
- 매 outdated detail: 매 maintenance.
|
||||
- 매 reader 의 cognitive overload.
|
||||
|
||||
→ 매 right level 의 abstraction.
|
||||
|
||||
### 매 progressive disclosure
|
||||
- 매 summary first.
|
||||
- 매 detail on demand.
|
||||
- 매 README → 매 ADR → 매 code.
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### Specific prompt template
|
||||
```
|
||||
ROLE: Senior backend engineer.
|
||||
TASK: Refactor function X.
|
||||
CONTEXT:
|
||||
- Current: throws on error.
|
||||
- Codebase: TypeScript, neverthrow library.
|
||||
|
||||
CONSTRAINTS:
|
||||
- Keep public signature unchanged.
|
||||
- Return Result<T, E>.
|
||||
- Add unit test for both branches.
|
||||
|
||||
OUTPUT FORMAT:
|
||||
- Code only, no explanation.
|
||||
- TypeScript with neverthrow.
|
||||
|
||||
EXAMPLE OUTPUT (for similar task):
|
||||
[paste example]
|
||||
|
||||
INPUT:
|
||||
[code]
|
||||
```
|
||||
|
||||
### Acceptance criteria (Given-When-Then)
|
||||
```gherkin
|
||||
Feature: Login
|
||||
Scenario: Valid credentials
|
||||
Given a registered user with email "user@example.com"
|
||||
And password "Pass123!"
|
||||
When they submit the login form
|
||||
Then they are redirected to /dashboard
|
||||
And a session cookie "sid" is set with HttpOnly and Secure flags
|
||||
|
||||
Scenario: Invalid password
|
||||
Given a registered user
|
||||
When they submit invalid password 5 times in 1 minute
|
||||
Then they are rate-limited for 15 minutes
|
||||
And a 429 status is returned
|
||||
```
|
||||
|
||||
### Bug report template
|
||||
```markdown
|
||||
## Reproducer
|
||||
1. Login as user@example.com
|
||||
2. Click "Export CSV" on /reports/123
|
||||
3. CSV downloads but contains BOM + wrong encoding
|
||||
|
||||
## Expected
|
||||
UTF-8 without BOM (matches docs).
|
||||
|
||||
## Actual
|
||||
UTF-16 with BOM. Excel opens it but Numbers crashes.
|
||||
|
||||
## Environment
|
||||
- macOS 15.2
|
||||
- Chrome 130.0.6723
|
||||
- App version 1.42.3 (commit abc123)
|
||||
|
||||
## Frequency
|
||||
100% — every export since deploy on 2026-05-08.
|
||||
|
||||
## Impact
|
||||
~200 users daily affected. Workaround: open in Excel.
|
||||
|
||||
## Logs
|
||||
[paste]
|
||||
```
|
||||
|
||||
### RFC template (short)
|
||||
```markdown
|
||||
# RFC-0042: Adopt Kafka for events
|
||||
|
||||
## Motivation
|
||||
3 services need async coordination. Sync HTTP causes cascade.
|
||||
|
||||
## Detailed design
|
||||
- Events: Avro schema.
|
||||
- Topic: domain.event_type.v{version}.
|
||||
- Retention: 7 days.
|
||||
- Consumer group per service.
|
||||
|
||||
## Drawbacks
|
||||
- Operational complexity (Kafka cluster).
|
||||
- Async debugging harder.
|
||||
|
||||
## Alternatives
|
||||
1. RabbitMQ — simpler, less throughput.
|
||||
2. SQS — vendor lock-in, less ordering.
|
||||
|
||||
## Unresolved
|
||||
- Schema registry choice.
|
||||
- DLQ strategy.
|
||||
|
||||
## Future
|
||||
- Stream processing (Flink).
|
||||
```
|
||||
|
||||
### Edge case checklist (function spec)
|
||||
```
|
||||
For function process(input):
|
||||
|
||||
Empty:
|
||||
[ ] input = null
|
||||
[ ] input = undefined
|
||||
[ ] input = ''
|
||||
[ ] input = []
|
||||
[ ] input = {}
|
||||
|
||||
Boundary:
|
||||
[ ] input.length = 0
|
||||
[ ] input.length = 1
|
||||
[ ] input.length = MAX_INT
|
||||
[ ] input.length = MAX_INT + 1
|
||||
|
||||
Type:
|
||||
[ ] input = number (expected string)
|
||||
[ ] input = string (expected number)
|
||||
[ ] input = function
|
||||
|
||||
Special:
|
||||
[ ] Unicode (emoji, RTL, combining)
|
||||
[ ] Negative numbers
|
||||
[ ] NaN, Infinity
|
||||
[ ] Concurrent calls
|
||||
[ ] Network failure mid-call
|
||||
```
|
||||
|
||||
## 🤔 결정 기준
|
||||
| 상황 | Detail level |
|
||||
|---|---|
|
||||
| Prompt to LLM | Maximum (constraint + example + format) |
|
||||
| Spec / RFC | High (motivation + design + alternatives) |
|
||||
| Bug report | High (repro + env + frequency) |
|
||||
| README | Medium (BLUF + 30s pitch) |
|
||||
| Slack message | Low (concise) |
|
||||
| Architecture diagram | Layered (C4) |
|
||||
|
||||
**기본값**: 매 audience + 매 task 의 calibrate. 매 vague 의 default 의 X.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Articulateness]]
|
||||
- 변형: [[Edge-Case-Enumeration]]
|
||||
- 응용: [[Prompt_Engineering|Prompt-Engineering]] · [[RFC]]
|
||||
- Adjacent: [[Progressive-Disclosure]] · [[ADR]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 LLM prompt. 매 spec 작성. 매 bug report. 매 design review.
|
||||
**언제 X**: 매 brainstorm (premature specificity). 매 creative explore.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **"매 user-friendly"** without metric: 매 unmeasurable.
|
||||
- **No edge case**: 매 production crash.
|
||||
- **Over-spec**: 매 implementation lock-in.
|
||||
- **No reproducer in bug**: 매 wasted reviewer time.
|
||||
- **No acceptance criteria**: 매 "done?" 의 ambiguous.
|
||||
- **No example in prompt**: 매 LLM 의 guess.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Pragmatic Programmer, RFC tradition, prompt engineering best practice).
|
||||
- 신뢰도 B.
|
||||
- Related: [[Articulateness]] · [[Prompt_Engineering|Prompt-Engineering]] · [[Spec-Writing]] · [[Edge-Case]].
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — specificity tool + prompt template + bug report + RFC + edge case checklist |
|
||||
Reference in New Issue
Block a user