Building a Living ADR System: Integrating Brainfork with Cursor and Claude Code

Architecture Decision Records (ADRs) are crucial for documenting why your system is built the way it is. But what if your ADRs weren't just static documents, but an active part of your development workflow? What if your AI coding assistants could check past decisions before suggesting changes?

That's exactly what Brainfork's decision logging makes possible when integrated with modern AI development tools like Cursor and Claude Code.

The Problem: ADRs Gathering Dust

We've all been there. You join a project and wonder, "Why is this service using PostgreSQL instead of MySQL?" or "Why did we choose this particular authentication pattern?" The answers might be buried in a wiki page, a Confluence document that hasn't been updated in months, or worse—lost in someone's memory who left the company.

Even when ADRs exist, they're often:

• Disconnected from the actual development process

• Static documents that nobody references during coding

• Outdated because updating them is a separate, manual process

• Ignored by AI assistants that suggest conflicting patterns

The Solution: Living ADRs with Brainfork

By integrating Brainfork's decision logging with Cursor and Claude Code, you create a system where:

1. AI assistants check past decisions before suggesting architectural changes

2. New decisions are automatically logged when significant changes are made

3. Your ADRs become queryable context that influences code generation

4. Decision history is always current because it's part of the development flow

Setting Up Brainfork with Cursor

Step 1: Connect Brainfork to Cursor

1. Go to the Server Management page in Brainfork

2. Find your server and click on "Easy Connections"

3. Click on the Cursor option—this will open Cursor automatically

4. When prompted, click "Needs Login" to complete authentication

5. Verify the tools are available in Cursor's config page

Step 2: Create a Cursor Rule for ADR Integration

Create a new rule file in your project's .cursor/rules/ directory:

1. Create the directory if it doesn't exist:

   bash

   Copy

   mkdir -p .cursor/rules

2. Create a new rule file:

   .cursor/rules/adr-integration.mdcmarkdown

   Copy

   1---
   2type: "Always"
   3description: "Check and log architecture decisions using Brainfork"
   4alwaysApply: true
   5---
   6# Architecture Decision Record Integration
   7You must integrate with Brainfork's decision logging system for all architectural changes.
   8
   9## Before Suggesting Changes
   10Always check for existing decisions:
   11- Use the `Brainfork:get_decisions` tool to search for relevant past decisions- Search keywords: database, auth, api, architecture, framework, deployment- If you find conflicting decisions, explain them and ask for confirmation before proceeding
   12## When Making Significant Changes
   13Significant changes that require ADR logging include:
   14- Database system changes or major schema modifications- Authentication/authorization pattern changes- API structure or versioning changes- Framework or major library switches- Deployment strategy changes- Performance optimization approaches- Security architecture updates
   15For these changes, use `Brainfork:log_decision` with this format:
   16```json
   17{
   18  "title": "Brief, clear description (e.g., 'Switch from PostgreSQL to MongoDB')",
   19  "context": "Current situation and what triggered this decision",
   20  "decisionNeeded": "The specific choice that needs to be made",
   21  "decisionMade": "The chosen solution and implementation approach",
   22  "reasoning": "Why this option? Trade-offs, alternatives evaluated, team impact",
   23  "tags": ["architecture", "database", "api", "auth", "deployment"]
   24}

Example Workflow

When asked to make an architectural change:

1. Search for related decisions first

2. If conflicts exist, present them to the developer

3. After implementing, log the decision immediately

4. Reference decision IDs in code comments when relevant

claude mcp add --transport http brainfork https://api.brainfork.is/test

Then authenticate by running inside Claude Code:

/mcp

Step 2: Create a Sub-Agent for ADR Management

Create a sub-agent using the /agents command or manually create a file:

Option 1: Using /agents command (Recommended) inside Claude Code

/agents

Then select "Create New Agent" and follow the prompts.

Option 2: Manual creation

Create .claude/agents/adr-guardian.md in your project:

1---
2name:
3description: "Architecture Decision Guardian - MUST BE USED for any architectural changes. Checks existing ADRs before making suggestions and logs new decisions. Use PROACTIVELY for database, API, auth, or infrastructure changes."
4tools:"Brainfork:get_decisions,Brainfork:log_decision,Brainfork:search,code_editor,file_viewer,directory_viewer"
5---
6# Architecture Decision Guardian
7You are an ADR-aware development assistant that ensures architectural consistency by checking past decisions and logging new ones.
8
9## Core Responsibilities
10### 1. Check Before Suggesting
11For ANY architectural suggestion or change:
12- **ALWAYS** use `Brainfork:get_decisions` first- Search keywords: database, cache, auth, api, deployment, framework, security- Read the full context of related decisions- Only suggest conflicting changes if there's a compelling reason
13### 2. Log Significant Changes
14You MUST log decisions for:
15- Database system or schema changes- Authentication/authorization patterns- API structure or versioning- Framework or major library adoption- Deployment or infrastructure changes- Performance optimization strategies- Security architecture updates
16### 3. Decision Format
17Use `Brainfork:log_decision` with complete information:
18```json
19{
20  "title": "Concise, searchable description",
21  "context": "Current state, problem, and trigger for change",
22  "decisionNeeded": "Specific choice requiring resolution",
23  "decisionMade": "Chosen solution with implementation details",
24  "reasoning": "Why this option? Alternatives considered, trade-offs, team impact",
25  "tags": ["architecture", "relevant-service", "technology-used"]
26}
27Workflow Examples
28### Example 1: Caching Addition
29User: "Add Redis for caching"
30Your process:
31Brainfork:get_decisions → search "cache", "redis", "performance"
32If no decision exists → implement and log
33If decision exists → explain it, ask if override needed
34
35### Example 2: Database Change
36User: "Switch to MongoDB"
37Your process:
38Brainfork:get_decisions → search "database", "mongodb", service name
39Present existing database decisions
40If proceeding → implement and log with migration plan
41
42## Best Practices
43Be Thorough: Include enough context for future understanding
44Link Decisions: Reference previous decision IDs when overriding
45Tag Consistently: Use standard tags for searchability
46Document Trade-offs: Always explain what we're giving up
47Think Long-term: Consider maintenance and team knowledge

Step 3: Activate the Sub-Agent

The sub-agent is now available in your Claude Code sessions. It will:

• Automatically activate when you mention architectural changes

• Be explicitly invokable with: `@adr-guardian help me design this API`

• Check past decisions before making suggestions

• Prompt you to log new architectural decisions

• Check for relevant ADRs before suggesting architectural changes

• Prompt to log decisions when making significant changes

• Help query and understand past architectural choices

Benefits of This Approach

1. Contextual Awareness: AI assistants understand your architectural history

2. Automatic Documentation: Decisions are logged as part of development

3. Reduced Architectural Drift: Past decisions are actively considered

4. Knowledge Preservation: Team decisions survive personnel changes

5. Searchable History: Query decisions by topic, service, or technology

Best Practices

• Tag Consistently: Use standard tags (database, api, auth, security, performance)

• Be Specific: Include enough context for future developers to understand

• Document Trade-offs: Always explain what you're giving up

• Reference Previous Decisions: Link to decisions you're superseding

• Review Periodically: Use get_decisions to audit your architecture

Getting Started Today

1. Set up your Brainfork server

2. Connect it to your preferred AI coding tool

3. Add the rules/sub-agent definitions to your project

4. Start coding with architectural awareness

Your ADRs transform from static documents into a living, breathing part of your development process—always current, always relevant, always helping you make better decisions.