Staff Engineer Archetypes | The Garnet Wiki

Staff engineers are the architects of engineering systems, the force behind long-term technical strategy, and the glue between teams, products, and platforms. This reference page identifies the recurring roles — or *archetypes* — that staff engineers assume in real, evolving organizations. Each archetype is defined by the actions they take, the decisions they make, and the patterns they sustain across projects and teams. Use this page when onboarding a new staff engineer, evaluating a candidate, or diagnosing a team’s technical leadership maturity.

Navigating Staff Engineer Roles by Objective

Onboarding a New Staff Engineer

When a new staff engineer joins, they must quickly understand not just *what* they do, but *how* they influence the organization. The onboarding process should surface the archetypes the new hire is likely to embody.

The first week should include a Staff Engineer Role Mapping exercise:

Read a recent architecture decision record (ADR) and annotate it with three questions:
*Who is the primary steward of this decision?*
*What evidence supports the trade-off chosen?*
*How was this decision communicated beyond the immediate team?*
Run git log --since="3 months ago" --grep="ADR" --oneline to find recent ADRs, then inspect the top five in a shared document.

The staff engineer is expected to own a domain, not just a service. A domain is a cohesive set of services, data models, and operational practices that serve a business function. To demonstrate ownership, they must:

Define the domain’s core invariant — a statement like:

> "All user profiles are updated within 30 seconds of any change to the user’s identity."

Document the domain’s health metrics in a domain-health.yaml file in the monorepo:

  domain: user-profiles
  metrics:
    - name: profile_update_latency
      query: |
        SELECT
          avg(latency) as avg,
          p95(latency) as p95,
          count(*) as count
        FROM profile_updates
        WHERE timestamp > now() - '1h'
      alert:
        threshold: 30000  # ms
        condition: "avg > threshold"
        notify: ["[email protected]", "[email protected]"]
    - name: profile_consistency
      query: |
        SELECT
          count(*) as total,
          sum(case when synced = true then 1 else 0 end) as synced
        FROM profile_sync_jobs
        WHERE last_updated > now() - '24h'
      alert:
        threshold: 0.95
        condition: "synced / total > threshold"

Failure occurs when the domain’s health metrics are not updated, or when new services are added without aligning to the core invariant.

Designing a System with Cross-Team Impact

When a staff engineer leads a system design that spans multiple teams, they must act as a System Integrator.

They begin by producing a High-Level Architecture Diagram using mermaid syntax in a docs/architecture.mmd file:

graph TD
    A[API Gateway] --> B[User Service]
    A --> C[Payment Service]
    B --> D[User Profile DB]
    C --> E[Payment DB]
    B --> F[Event Bus]
    C --> F
    F --> G[Notification Service]
    F --> H[Analytics Service]
    G --> I[Email Provider]
    H --> J[Data Warehouse]

The diagram is not a static image but a living document. Every service must have a system.yaml file in its root:

name: user-service
version: v1.2.0
dependencies:
  - name: event-bus
    version: ^2.0.0
    protocol: Kafka
    topic: user-updates
  - name: profile-db
    version: 1.3.4
    protocol: PostgreSQL
    schema: user_profiles
  - name: notification-service
    version: ^1.1.0
    protocol: gRPC
    endpoint: /v1/notify

The staff engineer ensures that all services use a common schema registry. A new field in the User schema must be versioned and backward-compatible. When a service publishes a new schema, it runs:

schema publish \
  --name User \
  --version 2.1.0 \
  --json-file schemas/user.json \
  --compatibility backward \
  --registry-url https://schema-registry.company.com

The system breaks silently when a service uses a schema version that is not registered, or when a new field is added without a default value, causing consumers to fail during deserialization.

Driving Technical Strategy Across the Organization

A staff engineer often leads Technology Adoption initiatives that influence the entire engineering organization.

To evaluate a new technology, they conduct a Technology Evaluation Workshop using a shared evaluation.yaml file:

technology: Kubernetes
evaluations:
  - team: frontend
    adoption_level: pilot
    feedback:
      pros:
        - "Excellent for stateless services"
        - "Built-in health checks"
      cons:
        - "Complex to debug"
        - "Requires deep understanding of CRDs"
    decision: "Proceed to rollout"
    next_steps:
      - "Define standard Helm chart template"
      - "Create cluster bootstrapping script"
      - "Schedule onboarding session"
  - team: data
    adoption_level: trial
    feedback:
      pros:
        - "Great for batch processing"
        - "Can run on shared cluster"
      cons:
        - "Need to manage custom resources"
        - "Slow deployment cycle"
    decision: "Wait for performance benchmarks"

The staff engineer uses this to draft a Technology Adoption Roadmap, a roadmap.yaml that defines milestones:

roadmap:
  phase: adoption
  timeline:
    - milestone: "Standardize on Helm charts"
      due: "2024-07-15"
      owner: "platform-engineering"
      status: "in-progress"
      dependencies:
        - "Kubernetes cluster setup"
        - "CI/CD pipeline for chart publishing"
    - milestone: "Enable self-service cluster provisioning"
      due: "2024-10-01"
      owner: "platform-engineering"
      status: "planning"
      dependencies:
        - "Helm chart standardization"
        - "RBAC and network policies"

The roadmap is not a static PDF but a living document. Every milestone is linked to a GitHub issue, and the staff engineer runs:

gh issue list --label "roadmap" --assignee "platform-engineering" --json title,labels,updatedAt --limit 10

Silent failure: teams adopt the technology but do not update the roadmap, causing the central team to lose visibility.

Improving Engineering Processes

When a staff engineer is tasked with raising the bar across teams, they act as a Process Champion.

They identify a recurring bottleneck — for example, slow architecture reviews — and implement a structured approach using Architecture Review Board (ARB) practices.

The ARB operates on a Review Cycle defined in arb-cycle.yaml:

cycle:
  duration: 2 weeks
  submissions:
    - format: ADR
      required_fields:
        - title
        - problem
        - proposed_solution
        - tradeoffs
        - alternatives
        - rationale
        - decision
        - impacts
      template: "docs/templates/adr-template.md"
    - review_process:
        - review_type: "initial"
          duration: 3 days
          reviewers: 3
          feedback: "pull request comments"
          decision: "approval or revision"
        - review_type: "final"
          duration: 5 days
          reviewers: 5
          feedback: "meeting with presenters"
          decision: "final approval"
  outcomes:
    - status: "approved"
      action: "merge ADR into monorepo"
    - status: "rejected"
      action: "return to author with feedback"
    - status: "deferred"
      action: "reschedule for next cycle"

The staff engineer ensures that every ADR is versioned and tracked in a database. They write a check-adr.sh script:

#!/bin/bash
set -euo pipefail

for file in ./adr/*.md; do
  title=$(grep -m1 "^# " "$file" | cut -d' ' -f2-)
  id=$(basename "$file" .md)
  if ! psql -t -c "SELECT id FROM adr WHERE id = '$id'" -c "INSERT INTO adr (id, title, status, created_at) VALUES ('$id', '$title', 'draft', now())"; then
    echo "ADR $id already exists"
  fi
done

A failure mode: a team submits an ADR but forgets to include the decision section, causing the ARB to reject it on a technicality.

Sustaining a Culture of Decision-Making

A staff engineer often becomes the Decision Arbiter — the person who ensures that decisions are not just made, but captured, communicated, and evolved.

They enforce a Decision Records standard using a decisions/ directory with YYYY-MM-DD-<title>.md files. Each decision record must include:

A Problem Statement with a clear “pain point”
A Solution Summary that is concise and executable
A Decision Log that tracks changes over time

An example: decisions/2024-03-15-choose-logging-stack.md



## Problem

Our services log to multiple formats: JSON, plain text, and structured events. Developers struggle to correlate logs across services. Observability tools consume logs inefficiently.

## Solution

Adopt OpenTelemetry Structured Logs (OTLP-logs) as the standard. All services emit logs in OTLP format, and all observability tools consume OTLP-logs.

## Tradeoffs

- **Cost**: Increased payload size, but better correlation.
- **Complexity**: Requires instrumentation, but enables unified trace and log views.
- **Adoption**: Team needs to learn OpenTelemetry, but gains long-term consistency.

## Decision

Accept OTLP-logs as the company logging standard. All new services must emit logs in OTLP format. Existing services should migrate over 6 months.

## Decision Log

| Date       | Change                       | Author         |
|------------|------------------------------|----------------|
| 2024-03-15 | Initial proposal             | Jane Doe       |
| 2024-03-22 | Added performance benchmarks | Alex Chen      |
| 2024-04-05 | Final approval               | Staff Engineering Team |

The staff engineer sets up a Decision Tracking Dashboard using a decisions/summary.md file:

# Decision Summary

## Active Decisions

| ID | Title | Status | Owner | Due |
|----|-------|--------|-------|-----|
| 2024-03-15 | Choose Logging Stack | approved | Jane Doe | 2025-03-15 |
| 2024-04-01 | Choose Message Broker | in-review | Alex Chen | 2024-06-15 |

## Recently Updated

- [2024-04-05] Choose Message Broker: Final feedback received
- [2024-04-03] Choose Database Schema Tool: Decision log updated

Failure: a decision is made but never documented, or a decision is updated without linking to the original proposal.

Common Pitfalls and Sharp Edges

Confusing “Ownership” with “Maintenance”

A staff engineer may define ownership of a domain but forget to define ownership boundaries. Teams assume responsibility for a service but not for its SLOs or SLIs.

The boundary is defined in a ownership-boundaries.yaml:

domain: user-profiles
owners:
  - team: user-service
    responsibilities:
      - "Handle user profile updates"
      - "Manage schema evolution"
      - "Monitor profile update latency"
    SLOs:
      - name: profile_update_latency
        target: "99% of updates < 30s"
        monitoring: "Prometheus"
        alerting: "Alertmanager"
    SLIs:
      - name: profile_update_latency
        query: "rate(profile_update_duration_seconds[5m])"
        window: "5m"

Silent failure: a team maintains a service but does not respond to alerts, and the domain’s SLOs are missed without any accountability.

Misunderstanding “Domain-Driven Design” in Practice

A staff engineer may adopt DDD but not enforce ubiquitous language. A service says “user” but the data model calls it “profile”, and the UI calls it “account”.

To fix this, they implement a Ubiquitous Language Sync process:

Every new ADR must include a Language Glossary section:

  ## Glossary

  - **User**: A person who uses the platform.
  - **Profile**: The persistent data associated with a User.
  - **Account**: A User’s subscription and billing information.

A check-ubiquitous-language.sh script validates that all services reference the glossary:

  for service in services/*; do
    if ! grep -q "User" "$service/README.md"; then
      echo "Service $service missing 'User' term"
    fi
    if ! grep -q "Profile" "$service/README.md"; then
      echo "Service $service missing 'Profile' term"
    fi
  done

Failure: services use inconsistent terms, and developers must guess meanings from context.

The Hidden Cost of “Standardization”

A staff engineer may push for a Standardized CI/CD Pipeline, but forget to define what “standard” means.

They define a ci-cd-standard.yaml:

pipeline:
  stages:
    - name: lint
      command: "npm run lint"
      image: "node:18"
    - name: test
      command: "npm run test"
      image: "node:18"
      env:
        - CI: "true"
        - TEST_DATABASE_URL: "postgresql://test-db:5432/test"
    - name: build
      command: "npm run build"
      image: "node:18"
    - name: deploy
      command: "kubectl apply -f k8s/"
      image: "kubernetes-helm:3.11"
      env:
        - DEPLOY_ENV: "staging"

But they forget to enforce the standard. The pipeline runs, but a service uses a different image or adds a step without updating the standard.

The staff engineer adds a verify-ci-cd.sh script:

#!/bin/bash
set -euo pipefail

for pipeline in .github/workflows/*.yaml; do
  if ! yq '.on.push.branches' "$pipeline" | grep -q "main"; then
    echo "Workflow $pipeline missing main branch trigger"
  fi
  if ! yq '.jobs.build.steps' "$pipeline" | yq '.[] | select(.name == "Build") | .uses' | grep -q "actions/checkout"; then
    echo "Workflow $pipeline missing checkout step"
  fi
done

Silent failure: pipelines are created but not aligned with the standard.

Summary of Staff Engineer Archetypes

Archetype	Key Actions	Common Failure Mode
Onboarding Guide	Define domain invariants, health metrics, and role mapping	Metrics not updated; domain boundaries unclear
System Integrator	Create shared schemas, maintain architecture diagrams, standardize protocols	Services use inconsistent schemas or protocols
Technology Adopter	Run evaluation workshops, maintain roadmaps, track adoption levels	Roadmaps become stale; adoption not documented
Process Champion	Standardize review cycles, enforce ADRs, track decisions	Reviews are delayed; decisions are lost in email
Decision Arbiter	Enforce decision records, maintain glossary, track decision lifecycle	Glossaries not updated; decisions lack traceability

These archetypes are not siloed; a staff engineer often embodies multiple. The true measure of their impact is not just code, but how teams think, decide, and collaborate.

This page was rewritten on 17 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.