2nd/10_Wiki/Topics/AI_and_ML/Development Communication Standards.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-development-communication-standa	Development Communication Standards	10_Wiki/Topics	verified	self	conventional commits conventional comments dev communication PR review standards	none	A	0.95	applied	development communication conventional-commits code-review standardization devops		2026-05-10	pending	language framework Standard Conventional Commits / Comments

Development Communication Standards

매 한 줄

"매 commit 의 message + 매 PR 의 review + 매 doc 의 standard". 매 Conventional Commits + Conventional Comments + ADR + RFC. 매 modern: 매 LLM-aided + 매 semantic versioning automation.

매 핵심

매 Conventional Commits

• 매 <type>(<scope>): <description>.
• 매 type: feat, fix, docs, style, refactor, perf, test, chore, build, ci.
• 매 BREAKING CHANGE: 매 footer 의 declare.

feat(auth): add OAuth2 PKCE flow
fix(api): handle null user in /me endpoint
docs(readme): update install steps
BREAKING CHANGE: drop Node 14 support

매 Conventional Comments (PR review)

• 매 <label> [decoration]: <subject>.
• 매 label: praise, nitpick, suggestion, issue, todo, question, thought, chore, note.
• 매 decoration: (non-blocking), (blocking), (if-minor).

suggestion: rename `data` to `userProfile` for clarity.
issue (blocking): this leaks the auth token in URL.
nitpick (non-blocking): trailing whitespace.
question: did you intend to swallow this exception?

매 PR title / description

• 매 short, imperative.
• 매 link issue.
• 매 motivation > diff.
• 매 testing 의 explain.

매 doc artifact

• ADR (Architecture Decision Record): 매 why (not what).
• RFC (Request For Comments): 매 design proposal.
• Runbook: 매 incident response.
• Postmortem: 매 blameless.

매 modern AI 의 영향

• LLM commit message: 매 git diff → 매 message.
• PR summarizer: 매 Anthropic Claude PR review.
• Auto-changelog: 매 release-please.
• Semantic version: 매 commit-based bump.

💻 패턴

Commit linter (commitlint)

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor', 'perf',
      'test', 'chore', 'build', 'ci', 'revert',
    ]],
    'subject-max-length': [2, 'always', 72],
  },
};

Husky hook

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Auto-changelog (release-please)

# .github/workflows/release.yml
on: { push: { branches: [main] } }
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node

LLM-generated commit

# 매 staged diff → 매 message
function llm_commit() {
  diff=$(git diff --cached)
  msg=$(echo "$diff" | llm "Write a Conventional Commit message for this diff. Output just the message.")
  git commit -m "$msg"
}

ADR template

# ADR-001: Use PostgreSQL over MongoDB

## Status
Accepted (2026-05-01)

## Context
We need a primary datastore for user profiles + transactions.

## Decision
PostgreSQL 16 with read replicas.

## Consequences
+ ACID transactions
+ Mature tooling
- Less flexibility for unstructured data
- Schema migration friction

RFC template

# RFC: Real-time notification system

## Summary
Replace polling with WebSocket-based push.

## Motivation
Current polling = 1M req/min, 80% wasted.

## Detailed Design
- Service: NestJS Gateway + Redis pub/sub
- Auth: JWT in handshake
- Fallback: SSE for legacy

## Alternatives
- SSE-only (rejected: bidirectional needed)
- Long polling (rejected: doesn't scale)

## Drawbacks
- Sticky session complexity
- Connection state

## Open Questions
- Multi-region routing?

Postmortem template (blameless)

# Incident: Auth outage 2026-05-08

## Summary
30-minute outage of /login endpoint.

## Timeline (UTC)
- 14:02 — Deploy of v2.3.1
- 14:05 — PagerDuty alert (HTTP 500 spike)
- 14:18 — Root cause identified (env var missing)
- 14:32 — Rolled back, traffic restored

## Root Cause
SECRET_KEY env var renamed in v2.3.1 but deploy config not updated.

## Action Items
- [ ] Add config validation pre-deploy (#1234)
- [ ] CI check for env var presence (#1235)
- [ ] Improve runbook for rollback (#1236)

## What Went Well
- Rollback under 30 minutes
- Clear ownership

## What Went Poorly
- No env var validation

PR description template

## What
<short summary>

## Why
<problem / motivation>

## How
<key implementation choice>

## Test plan
- [ ] Unit
- [ ] Integration
- [ ] Manual: ...

## Screenshots / Recordings (if UI)

Slack incident channel convention

#inc-2026-0508-auth-outage
- IC: @alice
- Comms: @bob
- Scribe: @carol
- Status: 🔴 → 🟡 → 🟢

매 결정 기준

상황	Standard
Commit	Conventional Commits
Code review	Conventional Comments
Architecture	ADR
New feature design	RFC
Incident	Postmortem (blameless)
Release	Semantic versioning + auto-changelog

기본값: 매 Conventional Commits + 매 commitlint + 매 release-please + 매 ADR / RFC for big decisions + 매 blameless postmortem.

🔗 Graph

• 부모: DevOps
• 변형: Conventional-Commits · ADR · RFC
• 응용: Code-Review · CI CD
• Adjacent: Postmortem-Culture

🤖 LLM 활용

언제: 매 team standardization. 매 LLM-aided commit / PR / doc. 언제 X: 매 solo throwaway script.

❌ 안티패턴

• Free-form commit: 매 changelog 의 generate X.
• Blame postmortem: 매 incident learning 의 kill.
• No ADR: 매 future why 의 lose.
• Wall-of-text PR: 매 review fatigue.
• No comment label: 매 reviewer 의 intent 의 ambiguous.

🧪 검증 / 중복

• Verified (conventionalcommits.org, conventionalcomments.org, Google SRE).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-01	P-Reinforce auto
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Conventional Commits / Comments + ADR / RFC / postmortem template