Files

T

Antigravity Agent 504fd5fb42 [G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00

9.5 KiB

Raw Blame History

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

title

Cognitive Constraints

매 한 줄

"매 architecture 의 organization 의 communication 의 mirror" (Conway 1967). 매 distributed system 의 cognitive load 의 explosion. 매 modern: Team Topologies (Skelton-Pais) — 매 stream-aligned + 매 platform + 매 enabling + 매 complicated subsystem.

매 핵심

Conway's Law (1967)

"Any organization that designs a system... will produce a design whose structure is a copy of the organization's communication structure."

→ 매 system 의 boundary = 매 team 의 boundary.

Inverse Conway Maneuver

매 desired architecture 의 force → 매 team structure 의 reorganize.
매 architecture-first organization design.
매 Spotify model, 매 Amazon "two-pizza team".

Team Topologies (Skelton & Pais 2019)

4 team type:

Stream-Aligned: 매 user-facing capability 의 own.
Platform: 매 internal infra service.
Enabling: 매 stream-aligned 의 specialty 의 transfer.
Complicated Subsystem: 매 specialist (ML, security).

3 interaction:

Collaboration: 매 close partnership.
X-as-a-Service: 매 platform 의 consume.
Facilitating: 매 enabling 의 support.

Cognitive Load (3 type, Sweller 1988)

Intrinsic: 매 task 의 inherent complexity.
Extraneous: 매 unnecessary (poor doc, friction).
Germane: 매 schema building (productive).

→ 매 team 의 capacity 의 finite — 매 design 의 reduce.

매 architecture 의 cognitive load

Pattern	Cognitive Load
Monolith	Mid (one big mental model)
Modular Monolith	Mid-Low
Microservices (small)	Per-service Low + 매 cross-system High
Serverless	Low per-function + 매 distributed High
Distributed Monolith	High (worst)

매 modern signal

DevEx (Developer Experience) 의 metric.
Cognitive load survey (DX scale).
Build time, deploy time, time-to-first-PR.
Onboarding 의 weeks.

매 응용

Org redesign: 매 architecture follow.
Microservices boundary: 매 team boundary 의 align.
Platform team: 매 "as-a-service".
Documentation: 매 reduce extraneous load.
Tooling: 매 abstract complexity.

매 anti-pattern

매 fragmented team (matrix maze).
매 god team (everyone everything).
매 platform 의 stream-aligned 의 confuse.
매 cognitive load 의 measure X.

💻 패턴 (응용)

Team Topologies design

teams:
  - name: Checkout
    type: stream-aligned
    domain: checkout / payment / cart
    consumes: [Platform/Auth, Platform/Notifications]
  
  - name: Search
    type: stream-aligned
    domain: search / recommendation
    consumes: [Platform/Data, Platform/ML]
  
  - name: Platform/Auth
    type: platform
    api: 'auth.example.com (OAuth, SSO)'
    consumed_by: [all stream-aligned]
  
  - name: Platform/Data
    type: platform
    api: 'event bus, data warehouse'
  
  - name: ML/Recommendation
    type: complicated_subsystem
    consumed_by: [Search]
  
  - name: SRE Enablement
    type: enabling
    works_with: [Checkout, Search]  # 매 transfer SRE practice
    duration: 'temporary, 6-12 months'

Cognitive load survey (DX)

def dx_survey(team):
    questions = [
        ('How easy is it to onboard new engineers?', 1, 5),
        ('How easy to find an answer to a code question?', 1, 5),
        ('How fast can you ship a small change end-to-end?', 1, 5),
        ('How confident are you the change won't break unrelated parts?', 1, 5),
        ('How clear are your team's responsibilities?', 1, 5),
    ]
    
    responses = collect_anonymous(team, questions)
    return {
        'avg_score': np.mean([r['score'] for r in responses]),
        'low_scores': [q for q, r in responses if r < 3],  # 매 priority
    }

Inverse Conway Maneuver

def design_org_for_architecture(target_architecture):
    """매 architecture → 매 team structure."""
    team_structure = []
    for service in target_architecture.services:
        if service.tier == 'product':
            team_structure.append({
                'name': f'{service.name} Team',
                'type': 'stream-aligned',
                'owns': service.bounded_context,
            })
        elif service.tier == 'platform':
            team_structure.append({
                'name': f'Platform/{service.name}',
                'type': 'platform',
                'sla': service.sla,
            })
    
    # 매 communication path 의 explicit
    for service_a, service_b in target_architecture.dependencies:
        team_a = find_team(team_structure, service_a)
        team_b = find_team(team_structure, service_b)
        team_a['interacts_with'] = team_a.get('interacts_with', []) + [{
            'team': team_b['name'],
            'type': 'x-as-a-service',
        }]
    
    return team_structure

Cognitive load reduction (platform pattern)

// 매 BEFORE: 매 team 의 매 service 의 모두 의 manage
class CheckoutTeamConcerns {
  // - DB connection pool config
  // - Kafka producer config
  // - Auth token refresh
  // - Logging / tracing setup
  // - Metric / alert setup
  // - K8s deployment YAML
  // - Secret rotation
  // - DR / backup
  // - ... + 매 actual checkout logic.
}

// 매 AFTER: 매 platform 의 abstraction
import { platform } from '@company/platform';

class Checkout {
  constructor(
    private auth = platform.auth,
    private db = platform.db.transactional,
    private events = platform.eventBus,
  ) {}
  
  async checkout(cart) {
    // 매 only domain logic.
    const user = await this.auth.requireUser();
    const order = await this.db.transaction(async (tx) => {
      const o = await tx.orders.create({ user, cart });
      await tx.payments.charge(o);
      return o;
    });
    await this.events.emit('order.created', order);
    return order;
  }
}

Documentation as load reduction

# Service: Checkout

## Why
[1 sentence]

## Architecture (C4 container level)
[diagram or link]

## How to run locally (5 min)
1. ...
2. ...

## Common questions
- Where is auth handled? → see Platform/Auth.
- How do I add a new payment method? → see ADR-0042.

## Who to ask
- General: @checkout-team
- Auth: @platform-auth
- DB: @platform-data

Bounded context boundary check

def check_team_alignment(team, services):
    """매 team 의 own 의 service 가 매 single bounded context?"""
    contexts = set(s.bounded_context for s in services if s.team == team.name)
    
    if len(contexts) > 2:
        return f'WARN: team {team.name} owns {len(contexts)} contexts — split risk'
    if len(contexts) == 0:
        return f'WARN: team {team.name} has no clear ownership'
    return 'OK'

Stream-aligned vs Platform decision

def classify_capability(capability):
    """매 stream vs platform 의 결정."""
    if capability.directly_user_facing and capability.differentiator:
        return 'stream-aligned'  # 매 own
    if capability.commodity and capability.consumed_by_many:
        return 'platform'  # 매 build platform OR 매 buy
    if capability.specialist_skill_required:
        return 'complicated-subsystem'
    return 'enabling-or-rotate'

🤔 결정 기준

상황	Approach
New product team	Stream-aligned + clear domain
Common infra	Platform team
Specialist (ML)	Complicated subsystem
Skill transfer	Enabling team (temporary)
Microservice mess	Modular monolith first
High cognitive load	Platform abstraction
Onboarding slow	Doc + golden path

기본값: Inverse Conway + 매 team-topology-aware design + 매 platform 의 reduce 매 load.

🔗 Graph

부모: Software-Architecture · Team-Design · Organization-Design
변형: Conway-Law · Team-Topologies · Inverse-Conway · Cognitive-Load-Theory
응용: Bounded-Contexts · Microservices · Platform-Engineering · DevEx
Adjacent: Architecture-Styles · Architecture-Anti-Patterns · Bottlenecks · Asset-Specific-Knowledge

🤖 LLM 활용

언제: 매 org redesign. 매 team boundary. 매 platform strategy. 매 onboarding optimization. 언제 X: 매 single team / single product. 매 < 5 person.

❌ 안티패턴

Architecture without team thought: 매 Conway 의 violate.
Matrix team (no clear owner): 매 ambiguity.
God team: 매 cognitive load 폭발.
Platform 의 ivory tower: 매 stream 의 ignore.
Microservices first (small team): 매 mismatch.
No doc: 매 extraneous load.

🧪 검증 / 중복

Verified (Conway 1967, Skelton-Pais 2019, Sweller cognitive load).
신뢰도 A.
Related: Architecture-Styles · Bounded-Contexts · Architecture-Anti-Patterns · Codebase_Onboarding_Guide · Asset-Specific-Knowledge.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Conway + Team Topologies + cognitive load + 매 platform abstraction code

9.5 KiB Raw Blame History

Cognitive Constraints

매 한 줄

매 핵심

Conway's Law (1967)

Inverse Conway Maneuver

Team Topologies (Skelton & Pais 2019)

Cognitive Load (3 type, Sweller 1988)

매 architecture 의 cognitive load

매 modern signal

매 응용

매 anti-pattern

💻 패턴 (응용)

Team Topologies design

Cognitive load survey (DX)

Inverse Conway Maneuver

Cognitive load reduction (platform pattern)

Documentation as load reduction

Bounded context boundary check

Stream-aligned vs Platform decision

🤔 결정 기준

🔗 Graph

🤖 LLM 활용

❌ 안티패턴

🧪 검증 / 중복

🕓 Changelog

9.5 KiB

Raw Blame History