adr-aware

description: Automatically load and apply relevant ADRs when creating or modifying resources tags: [adr, architecture, design, conventions] techStack: [all] appliesTo: ["/*.cs", "/.ts", "**/.tsx"] alwaysApply: true

Purpose

Ensures Architecture Decision Records (ADRs) are automatically considered when AI agents create or modify code. This skill provides proactive ADR awareness versus reactive checking (which is handled by

adr-check

Philosophy:

• adr-aware

  (this skill) = BEFORE - Load relevant ADRs when starting work

• adr-check

  = AFTER - Validate completed work against all ADRs

Always-Apply Rules

Rule 1: Resource-Type to ADR Mapping

When creating or modifying these resource types, automatically load the specified ADRs:

*Endpoints.cs

*Handler.cs

Program.cs

Api/Ai/*

*DocumentIntelligence*

*Analysis*

*Ai*

*Authorization*.cs

*Filter.cs

*Policy*.cs

*Cache*.cs

IDistributedCache

IMemoryCache

*Plugin.cs

*Spe*.cs

*Graph*.cs

*Drive*.cs

*.tsx

ControlManifest.Input.xml

*.js

Program.cs

Add*

*Worker.cs

*Service.cs

BackgroundService

*JobStatus*

JobOutcome

JobContract

*Feature*

FeatureFlag

IOptions*

ProblemDetails

Results.Problem

IResult

v1/

ApiVersion

*Store*.cs

*Document*.cs

*File*.cs

Rule 2: Automatic Context Loading (Two-Tier Strategy)

When a task or prompt involves creating/modifying files matching the patterns above:

BEFORE writing any code:
  1. IDENTIFY resource types from task/file patterns
  2. LOOKUP applicable ADRs from mapping table (Rule 1)

  3. LOAD Tier 1 context (concise, AI-optimized):
     a. LOAD .claude/constraints/{domain}.md for MUST/MUST NOT rules
        - API work → .claude/constraints/api.md
        - PCF work → .claude/constraints/pcf.md
        - Plugin work → .claude/constraints/plugins.md
        - Auth work → .claude/constraints/auth.md
        - Caching work → .claude/constraints/data.md
        - AI work → .claude/constraints/ai.md
        - Testing → .claude/constraints/testing.md

     b. LOAD .claude/adr/ADR-XXX.md for each applicable ADR
        - These are 100-150 line concise versions
        - Focus on constraints, not full rationale

     c. LOAD .claude/patterns/{domain}/*.md for code examples
        - API patterns → .claude/patterns/api/
        - Auth patterns → .claude/patterns/auth/
        - PCF patterns → .claude/patterns/pcf/
        - Dataverse patterns → .claude/patterns/dataverse/

  4. IF more context needed (rare):
     → READ docs/adr/ADR-XXX-*.md for full rationale and history

  5. APPLY constraints during implementation

Resource Type to Context Files Mapping

.claude/constraints/api.md

.claude/patterns/api/

.claude/constraints/pcf.md

.claude/patterns/pcf/

.claude/constraints/plugins.md

.claude/patterns/dataverse/

.claude/constraints/auth.md

.claude/patterns/auth/

.claude/constraints/data.md

.claude/patterns/caching/

.claude/constraints/ai.md

.claude/patterns/ai/

.claude/constraints/jobs.md

.claude/constraints/testing.md

.claude/patterns/testing/

Rule 3: ADR Constraint Comments

When writing code affected by ADRs, include a brief ADR reference comment:

// ✅ DO: Reference ADRs in significant architectural code
public static class NavMapEndpoints
{
    /// <summary>
    /// ADR Compliance:
    /// - ADR-001: Minimal API (no controllers)
    /// - ADR-008: Endpoint-level authorization
    /// - ADR-009: Redis-first caching (L1 exception for metadata)
    /// </summary>
    public static void MapNavMapEndpoints(this WebApplication app) { }
}

// ❌ DON'T: Clutter every method - only significant decisions
public string FormatDate(DateTime dt) => dt.ToString("yyyy-MM-dd"); // No ADR ref needed

Rule 4: ADR Violation Prevention

If about to write code that violates an ADR:

IF detected violation pattern:
  1. STOP before writing
  2. NOTIFY user with:
     🔔 **ADR Conflict Detected**
     
     **ADR**: {ADR-XXX} - {Title}
     **Constraint**: {Specific rule being violated}
     **Intended Code**: {What you were about to write}
     **Compliant Alternative**: {What to write instead}
     
     Proceed with compliant alternative? (y/n)
  3. AWAIT confirmation before continuing

ADR Quick Reference

Reference this table for common constraints. The source of truth is:

• Concise ADRs:

  .claude/adr/

  (AI-optimized, 100-150 lines each)
• Full ADRs:

  docs/adr/INDEX.md

  (complete with history and rationale)

[FunctionName]

Microsoft.Azure.Functions

HttpClient

IAuthorizationXxx

Task.Run

CreateFolder

.js

Microsoft.Graph

app.UseAuthorization()

IMemoryCache

Integration with Other Skills

design-to-project

• Phase 2 (Context) should invoke ADR lookup using the mapping table
• Generated CLAUDE.md should list applicable ADRs

task-create

• Task

  <constraints>

  should include ADR references
• Task

  <files>

  should include ADRs to read

code-review

• Should reference this skill for ADR-specific checks
• Violations should cite specific ADR numbers

adr-check

• This skill prevents violations; adr-check validates afterward
• Both should use the same ADR quick reference

Examples

Example 1: Creating a new API endpoint

Task: "Create a new endpoint to get document metadata"

adr-aware activates:

Detected: API Endpoint creation
Loading ADRs: ADR-001, ADR-008, ADR-010

Key constraints:
- ADR-001: Use Minimal API pattern (MapGet/MapPost), not controllers
- ADR-008: Add endpoint filter for authorization, not global middleware
- ADR-010: Inject concrete SpeFileStore, not interface

Generated code includes:

// ADR-001: Minimal API pattern
app.MapGet("/api/documents/{id}/metadata", GetDocumentMetadataAsync)
   .AddEndpointFilter<DocumentAuthorizationFilter>()  // ADR-008
   .WithName("GetDocumentMetadata");

Example 2: Creating a PCF control

Task: "Create a document viewer PCF control"

adr-aware activates:

Detected: PCF Control creation
Loading ADRs: ADR-006, ADR-011, ADR-012, ADR-021

Key constraints:
- ADR-006: Use PCF, not webresource (already doing this ✅)
- ADR-011: Use Dataset PCF for list views
- ADR-012: Import from @spaarke/ui-components for shared components
- ADR-021: Use Fluent v9, semantic tokens, dark mode support

Generated code includes:

// ADR-012: Use shared component library
import { DocumentCard, StatusBadge } from "@spaarke/ui-components";
// ADR-021: Fluent v9 components and tokens
import { Button, tokens, makeStyles } from "@fluentui/react-components";
import { DocumentAdd20Regular } from "@fluentui/react-icons";

const useStyles = makeStyles({
  container: {
    backgroundColor: tokens.colorNeutralBackground1, // ADR-021: semantic tokens
    color: tokens.colorNeutralForeground1,
  },
});

Example 3: Prevented violation

Task: "Add caching to the document service"

adr-aware detects:

About to use IMemoryCache for cross-request caching...

🔔 **ADR Conflict Detected**

**ADR**: ADR-009 - Redis-first caching
**Constraint**: No hybrid L1+L2 cache; use IDistributedCache for cross-request
**Intended Code**: `_memoryCache.Set(key, value, TimeSpan.FromMinutes(5))`
**Compliant Alternative**: `await _distributedCache.SetStringAsync(key, json, options)`

Proceed with compliant alternative? (y/n)

Validation

Run

/adr-check

Last updated: December 25, 2025