agentleFS
animuscrmsfdcanimuscrmsfdc/salesforce-vibe-coding/.claude/skills/architecture-decision-records/SKILL.md

architecture-decision-records

Skill0 starsChanged 6 months agoMITView on GitHub

Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is. Tailored for Salesforce Apex / metadata projects.

70 other projects use a version of this, 26 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use nuxt4-patterns, dart-flutter-patterns and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • loulanyueSkill

    nuxt4-patterns

    Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.

    Also in 8 projects that use this

  • RojiosSkill

    dart-flutter-patterns

    Production-ready Dart and Flutter patterns covering null safety, immutable state, async composition, widget architecture, popular state management frameworks (BLoC, Riverpod, Provider), GoRouter navigation, Dio networking, Freezed code generation, and clean architecture.

    Also in 5 projects that use this

  • royaluniondesign-sysSkill

    content-hash-cache-pattern

    Cache expensive file processing results using SHA-256 content hashes — path-independent, auto-invalidating, with service layer separation.

    Also in 11 projects that use this

  • Yog-SothoSkill

    pytorch-patterns

    PyTorch deep learning patterns and best practices for building robust, efficient, and reproducible training pipelines, model architectures, and data loading. Always activate when the user is writing PyTorch models or training scripts, reviewing deep learning code, debugging training loops or data pipelines, optimizing GPU memory or training speed, setting up reproducible experiments, implementing transfer learning or fine-tuning, or asks anything about nn.Module, DataLoader, autograd, AMP, or torch.compile.

    Also in 11 projects that use this

  • junimnjwSkill

    ralphinho-rfc-pipeline

    RFC-driven multi-agent DAG execution pattern with quality gates, merge queues, and work unit orchestration.

    Also in 7 projects that use this

  • junimnjwSkill

    carrier-relationship-management

    Codified expertise for managing carrier portfolios, negotiating freight rates, tracking carrier performance, allocating freight, and maintaining strategic carrier relationships. Informed by transportation managers with 15+ years experience. Includes scorecarding frameworks, RFP processes, market intelligence, and compliance vetting. Use when managing carriers, negotiating rates, evaluating carrier performance, or building freight strategies.

    Also in 6 projects that use this

  • +2 more from junimnjw

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 66 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the lightweight ADR format proposed by Michael Nygard, adapted for Salesforce development:

    line 21
  2. Distinctive:

    When a decision moment is detected:

    line 75
  3. Distinctive:

    When a user asks "why did we choose X?":

    line 88
  4. Very specific:

    Check if docs/adr/ exists — if not, respond: "No ADRs found in this project.

    line 90
  5. Very specific:

    If it exists, scan docs/adr/README.md index for relevant entries

    line 91
  6. Distinctive:

    Read matching ADR files and present the Context and Decision sections

    line 92
  7. Distinctive:

    If no match is found, respond: "No ADR found for that decision.

    line 93
  8. Distinctive:

    Write essays — if the context section exceeds 10 lines, it's too long

    line 170
  9. Distinctive:

    salesforce-developer-apex: when establishing a new Apex pattern (trigger handler, service layer), suggest creating an ADR

    line 189
  10. Distinctive:

    salesforce-admin: when choosing between declarative automation options, suggest creating an ADR

    line 190
  11. Distinctive:

    salesforce-devops: when selecting a deployment or branching strategy, suggest creating an ADR

    line 191

“Common” is measured: kept by at least 6 in 10 of the 66 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

Architecture Decision Records

Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code.

When to Activate

  • User explicitly says "let's record this decision" or "ADR this"
  • User chooses between significant alternatives (trigger pattern, sharing model, event strategy, integration approach)
  • User says "we decided to..." or "the reason we're doing X instead of Y is..."
  • User asks "why did we choose X?" (read existing ADRs)
  • During planning phases when architectural trade-offs are discussed

ADR Format

Use the lightweight ADR format proposed by Michael Nygard, adapted for Salesforce development:

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
**Salesforce Area**: [Apex | Metadata | Integration | Security | Data Model | DevOps | Testing]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, governor limits, org configuration, or Salesforce-specific forces at play]

## Decision

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly. Include the Apex class, object, or metadata component affected where relevant.]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected — include governor limit impact, security implications, or maintainability concerns where applicable]

### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [trade-off 1]
- [trade-off 2]

### Risks
- [risk and mitigation — call out governor limit risks, sharing model side effects, or deployment order dependencies]

Workflow

Capturing a New ADR

When a decision moment is detected:

  1. Initialize (first time only) — if docs/adr/ does not exist, ask the user for confirmation before creating the directory, a README.md seeded with the index table header (see ADR Index Format below), and a blank template.md for manual use. Do not create files without explicit consent.
  2. Identify the decision — extract the core architectural choice being made
  3. Gather context — what problem prompted this? What Salesforce constraints exist (governor limits, sharing model, deployment order)?
  4. Document alternatives — what other options were considered? Why were they rejected?
  5. State consequences — what are the trade-offs? What becomes easier/harder?
  6. Assign a number — scan existing ADRs in docs/adr/ and increment
  7. Confirm and write — present the draft ADR to the user for review. Only write to docs/adr/NNNN-decision-title.md after explicit approval. If the user declines, discard the draft without writing any files.
  8. Update the index — append to docs/adr/README.md

Reading Existing ADRs

When a user asks "why did we choose X?":

  1. Check if docs/adr/ exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
  2. If it exists, scan docs/adr/README.md index for relevant entries
  3. Read matching ADR files and present the Context and Decision sections
  4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"

ADR Directory Structure

docs/
└── adr/
    ├── README.md                              ← index of all ADRs
    ├── 0001-trigger-handler-pattern.md
    ├── 0002-platform-events-over-flows.md
    ├── 0003-custom-metadata-for-config.md
    └── template.md                            ← blank template for manual use

ADR Index Format

# Architecture Decision Records

| ADR | Title | Area | Status | Date |
|-----|-------|------|--------|------|
| [0001](0001-trigger-handler-pattern.md) | Static switch-based trigger handler pattern | Apex | accepted | 2026-01-15 |
| [0002](0002-platform-events-over-flows.md) | Platform Events over Process Builder for async processing | Integration | accepted | 2026-01-20 |
| [0003](0003-custom-metadata-for-config.md) | Custom Metadata over Custom Settings for feature flags | Data Model | accepted | 2026-02-01 |

Decision Detection Signals

Watch for these patterns in conversation that indicate an architectural decision:

Explicit signals

  • "Let's go with X"
  • "We should use X instead of Y"
  • "The trade-off is worth it because..."
  • "Record this as an ADR"

Implicit signals (suggest recording an ADR — do not auto-create without user confirmation)

  • Choosing between trigger handler patterns
  • Selecting a sharing model (with sharing vs inherited sharing vs service-layer without sharing)
  • Deciding between Platform Events, Change Data Capture, Flows, or Process Builder for async automation
  • Choosing Custom Metadata vs Custom Settings vs Custom Labels for configuration
  • Picking an integration pattern (REST callout vs Platform Events vs MuleSoft)
  • Making a SOQL security enforcement choice (WITH SECURITY_ENFORCED vs Security.stripInaccessible())
  • Deciding on a batch vs queueable vs future method approach
  • Selecting a test data strategy (@TestSetup vs factories vs static data)
  • Branching / deployment strategy choices (scratch orgs, sandboxes, CI pipeline)

Salesforce-Specific Decision Categories

CategorySalesforce Examples
Apex patternsTrigger handler pattern, service/selector/domain layers, bulkification approach
Async processingBatch Apex vs Queueable vs Future vs Platform Events vs Flows
Automation layerFlow vs Apex trigger vs Workflow (deprecated) vs Process Builder (deprecated)
Configuration storageCustom Metadata vs Custom Settings vs Custom Labels vs Hierarchy Settings
Security enforcementWITH SECURITY_ENFORCED vs Security.stripInaccessible(), sharing model per class
IntegrationREST callouts vs Platform Events vs Named Credentials vs MuleSoft
Data modelingJunction objects, polymorphic lookups, External Objects, Big Objects
UI layerLWC vs Aura vs Visualforce vs Flow Screens
TestingTest data factories vs @TestSetup, mock strategies, coverage thresholds
DevOpsPackage development vs org development, scratch org workflow, CI/CD tooling
API versioningWhen to bump API version, which components to include in a deployment

What Makes a Good ADR

Do

  • Be specific — "Use static switch-based handler in ExceptionTriggerHandler" not "use a handler class"
  • Reference Salesforce constraints — governor limits, sharing considerations, deployment order dependencies
  • Record the why — the rationale matters more than the what
  • Include rejected alternatives — future developers need to know what was considered (e.g., why Flows were rejected)
  • State consequences honestly — every decision has trade-offs
  • Keep it short — an ADR should be readable in 2 minutes
  • Use present tense — "We use X" not "We will use X"
  • Name affected components — reference the Apex class, object API name, or metadata component

Don't

  • Record trivial decisions — field label wording or minor formatting choices don't need ADRs
  • Write essays — if the context section exceeds 10 lines, it's too long
  • Omit alternatives — "we just picked it" is not a valid rationale
  • Backfill without marking it — if recording a past decision, note the original date
  • Let ADRs go stale — superseded decisions should reference their replacement
  • Assume Salesforce defaults are obvious — document why a non-default sharing model or CRUD bypass was chosen

ADR Lifecycle

proposed → accepted → [deprecated | superseded by ADR-NNNN]
  • proposed: decision is under discussion, not yet committed
  • accepted: decision is in effect and being followed
  • deprecated: decision is no longer relevant (e.g., feature removed, Process Builder retired)
  • superseded: a newer ADR replaces this one (always link the replacement)

Integration with Other Skills

  • salesforce-developer-apex: when establishing a new Apex pattern (trigger handler, service layer), suggest creating an ADR
  • salesforce-admin: when choosing between declarative automation options, suggest creating an ADR
  • salesforce-devops: when selecting a deployment or branching strategy, suggest creating an ADR
  • find-weaknesses: security or architecture findings that require a structural fix may warrant an ADR to capture the decision

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.