2nd/10_Wiki/Topics/AI_and_ML/Be-Detailed.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-be-detailed	Be Detailed (Specificity Principle)	10_Wiki/Topics	verified	self	구체화 specificity prompt detail requirement specification edge case enumeration	none	B	0.85	applied	communication prompt-engineering requirements spec detail edge-case anti-vague		2026-05-10	pending	language applicable_to communication / spec 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)

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

## 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)

# 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 · 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 · 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