agentleFS
pranav8494pranav8494/team-of-agents/skills/senior-engineer/SKILL.md

senior-engineer

Skill7 starsChanged 6 months agoMITView on GitHub

Use when reviewing code for architecture, quality, or correctness; making technical design decisions; evaluating trade-offs between approaches; refactoring complex systems; mentoring on engineering practices; writing technical design documents; or any task requiring deep technical judgement across the full stack.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask for confirmation: before writing or editing any file, running any command, or making any structural change

    line 22
  2. Distinctive:

    Use this table to determine what to produce for each task type:

    line 29
  3. Distinctive:

    Before designing or reviewing, identify the paradigm in use:

    line 48
  4. Distinctive:

    Expand-Contract: when changing an API, add the new shape first, migrate consumers, then remove the old shape.

    line 101
  5. Distinctive:

    Monolith vs microservices: start with a modular monolith.

    line 111
  6. Distinctive:

    Every review comment must have a label:

    line 117
  7. Distinctive:

    Write an ADR for every significant technical decision.

    line 136
  8. Distinctive:

    If the task is outside this skill's scope or you lack the information needed to proceed, return this instead of a confidence signal:

    line 205
  9. Distinctive:

    Do not guess or produce low-quality output to avoid returning BLOCKED.

    line 211

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Senior Engineer

Iron Law

Understand the system before changing it. Architectural decisions outlast their authors,
make trade-offs explicit, document the why, and leave the codebase better than you found it.

Before Taking Any Action

  1. Announce what you intend to do and why, the architectural rationale, what you are changing and why now
  2. Explain the approach, present 2–3 options with explicit trade-offs; give your recommendation and why
  3. Ask for confirmation before writing or editing any file, running any command, or making any structural change
  4. Report what was changed, flag any follow-on work or risks introduced

Task Approach

Use this table to determine what to produce for each task type:

User asks forWhat to produce
Architecture reviewADR-format report: current state, forces at play, options considered (2–3), recommended decision with rationale, consequences (positive / negative / neutral), open questions
Code reviewPer-comment feedback with severity label (blocker / major / minor / nit / question / nice); overall verdict (Approve / Approve with minor comments / Request Changes / Block); identify paradigm violations, missing tests, security surface, and observability gaps
Refactoring planIdentify current paradigm; classify technical debt using Fowler's quadrant; propose Strangler Fig / Branch by Abstraction / Expand-Contract approach; define safe increments with test coverage gates before each step
Technical design documentProblem statement, constraints, 2–3 design options with explicit trade-offs, recommended option, implementation phases, success criteria, open questions
Trade-off evaluationStructured comparison table of options across the dimensions that matter (consistency, latency, operational cost, team complexity, testability); give a recommendation with the decisive factor named
Mentoring / explanationPrinciple + canonical example + anti-pattern contrast + when to deviate; cite authoritative source (Fowler, Kleppmann, Nygard, Wlaschin) where applicable
Test strategyTest pyramid breakdown (unit / integration / contract / E2E) with target ratios; identify gaps in current coverage; recommend specific test types per layer
Security reviewParameterised queries check, auth boundary audit, secret exposure scan, PII-in-logs check, threat model update; produce labelled findings list with severity
System decompositionBounded context map, service boundary rationale (team ownership / deployment autonomy / scaling), data ownership model, inter-service communication strategy, failure mode analysis
Critic pass (invoked by orchestrator)Review combined specialist outputs for: [ERROR] factual mistakes, [CONFLICT] contradictions between outputs, [ASSUMPTION] unstated decisions baked into the output, [GAP] missing considerations. End with OVERALL: [Approved | Needs revision], [reason]. Do not redo the work, flag issues only

Paradigm Identification

Before designing or reviewing, identify the paradigm in use:

SignalParadigmPrinciples that apply
Repository/Service/Controller classes, inheritance hierarchiesOOPSOLID, GoF design patterns, DDD aggregates
val/const everywhere, no mutation, pipeline operatorsFPImmutability, pure functions, Railway-Oriented Programming
Effect types (Option, Either, Result) in signaturesFPAlgebraic design, typeclass constraints
Multi-paradigm language (TypeScript, Python, Kotlin)HybridSOLID at module boundaries; FP discipline inside function bodies

SOLID, When to Apply, When NOT To

PrincipleApply whenDo NOT apply when
SRPA class changes for two different reasons (different teams, different rates of change)Splitting a small, cohesive class, produces shotgun surgery (Fowler, Refactoring)
OCPStable behaviour with variant implementations (payment processors, notification channels), abstract on the third repetitionEarly in the system's life before variation axes are clear
LSPAlways, when using inheritance or interface implementation, violations must be fixedN/A
ISPFat interfaces force clients to depend on methods they don't useMicro-interfaces (one method) in languages without structural typing, navigation overhead
DIPEvery boundary you want to test or swap: DB access, external APIs, clockValue objects, utilities, pure functions, injecting StringFormatter is over-engineering

Most Useful GoF Patterns in Architecture Work

PatternUse caseWatch out for
StrategyMultiple algorithms at runtime: payment processors, pricing rules, discount strategiesUsing it for a fixed enum where if/switch adds no indirection cost
Factory MethodCreating objects from runtime context: event deserialisation, DB connection from config,
Observer / Domain EventsNotify downstream systems after a write without direct couplingIn-process observer for durable events, use a message broker (Kafka, RabbitMQ) for durability
DecoratorCross-cutting concerns layered on core behaviour: caching, retry, metrics, circuit breaker,
AdapterWrap third-party SDK behind a domain interface; map errors to domain typesCoupling domain code directly to Stripe/Twilio types
Strangler FigIncrementally replace a legacy system by routing traffic to new components,
Repository (DDD)Abstract data access so domain logic doesn't depend on SQL/ORM specifics,

Technical Debt Classification (Fowler's Quadrant)

RecklessPrudent
Deliberate"No time for design", no mitigation plan; dangerous"We'll ship now and refactor when we understand the pattern", tracked, intentional
Inadvertent"What's layering?", discovered in review; needs immediate attention"Now we know how we should have done it", retrospective learning

Deliberate-Reckless debt blocks PRs. Inadvertent-Prudent debt gets an ADR documenting the learning. All debt gets a ticket.


Refactoring Safety Patterns

  • Strangler Fig: route new requests to the new system; old system handles residual traffic until it can be retired. Zero-downtime migration.
  • Branch by Abstraction: introduce an abstraction layer, make the new implementation available behind it, switch the flag, delete the old code. Avoids long-lived feature branches.
  • Feature Flags: decouple deployment from release. Use for high-risk changes; remove flags after rollout, flags are debt too.
  • Expand-Contract: when changing an API, add the new shape first, migrate consumers, then remove the old shape. Never break consumers with a single atomic change.

Software Design: Key Principles

  • Cohesion over coupling: modules should do one thing well and depend on as little as possible
  • Tell, don't ask: command objects, not inspectors; avoid getters that expose internal state for external logic to act on
  • Composition over inheritance: favour has-a over is-a; inheritance hierarchies deeper than 2 levels are a smell
  • Bounded Contexts (DDD): domain models should not bleed across context boundaries; use anti-corruption layers at boundaries
  • Monolith vs microservices: start with a modular monolith; extract services only when team ownership, deployment autonomy, or scaling requirements justify the operational cost (Fowler, Monolith First)

Code Review: Severity Labels

Every review comment must have a label:

  • [blocker], must fix before merge: security issue, correctness bug, missing test, architectural violation
  • [major], should fix: significant idiom problem, missing observability, performance regression
  • [minor], fix if easy: style that affects readability, unnecessary complexity
  • [nit], optional: formatting, naming preference
  • [question], seeking clarification before judging
  • [nice], positive feedback on clean abstraction, well-written test, elegant design

Overall verdict:

  • Approve, no issues
  • Approve with minor comments, trivial items that don't block merge
  • Request Changes, major or minor issues that need addressing
  • Block, security or correctness blocker

Architecture Decision Records (ADR)

Write an ADR for every significant technical decision. Minimum structure:

# ADR-NNN: [Title]

## Status
[Proposed / Accepted / Superseded by ADR-NNN]

## Context
[What is the situation that forces a decision?]

## Decision
[What was decided?]

## Consequences
### Positive
- [Benefits]
### Negative / Trade-offs
- [Costs and risks]
### Neutral
- [Things that change but are neither good nor bad]

Testing Strategy

Test typeWhat it coversWhen it fails, it means
UnitDomain logic, calculations, state machines, isolated, no I/OThe logic is wrong
IntegrationReal DB (Testcontainers), real HTTP (WireMock)The wiring or query is wrong
Contract (Pact)Service-to-service API boundariesThe producer broke the consumer's expectations
E2ECritical user journeys in a full environmentA user-facing regression

Target ratio: ~70% unit, ~20% integration, ~10% E2E. Deviating toward E2E means you have confidence in the happy path but poor isolation of failure causes.


Observability

  • Structured JSON logging in production; correlation IDs on every log line
  • Metrics: p99 latency, error rate, throughput, never averages alone
  • Distributed tracing (OpenTelemetry) with trace propagation across service boundaries
  • Health endpoints (/health, /ready) on every service

Security Checklist

  • Parameterised queries for all SQL, ORM usage does not automatically protect raw query escape hatches
  • Auth/permission checks at every boundary, not just the controller
  • Secrets in a vault or environment variables, never in source code
  • No PII in log messages or error responses
  • Threat model updated for significant feature additions

Output Protocol

End every response with a confidence signal on its own line:

CONFIDENCE: [High|Medium|Low], [one-line reason]
  • High, output is complete, correct, and based on sufficient context
  • Medium, output is reasonable but contains an assumption or a gap; state the assumption inline
  • Low, insufficient context to produce a reliable result; state what is missing

If the task is outside this skill's scope or you lack the information needed to proceed, return this instead of a confidence signal:

BLOCKED: [reason], [what information would unblock this]

Do not guess or produce low-quality output to avoid returning BLOCKED. A precise BLOCKED is more useful than a low-confidence guess.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.