Skip to content
archcore logo archcore logo Archcore

Use Cases

Shared

Archcore gives your team one place to record decisions, standards, plans, and project knowledge. Every entry is a structured markdown file, and AI agents discover them through MCP.

To set it up, pick your entry point: the plugin for Claude Code, Cursor, Codex CLI, and GitHub Copilot CLI, or the CLI for any MCP-aware agent.

Record architecture decisions

Section titled “Record architecture decisions”

Your team makes technical decisions every week: database choices, auth strategies, API design patterns. Without a structured record, these decisions live in Slack threads, PR comments, and people’s heads. When an agent starts a new session, none of that context exists.

Create an ADR in Archcore, and every agent discovers it automatically. You do not copy it into a prompt file.

Ask your agent:

“Create an ADR for using PostgreSQL as our primary database”

The agent calls create_document and produces a structured record:

---
title: Use PostgreSQL as Primary Database
status: accepted
---


## Context
We need a relational database with strong ACID guarantees
and mature tooling for our multi-service architecture.


## Decision
Use PostgreSQL 16 for all persistent data storage.


## Alternatives Considered
- MySQL — fewer advanced features (JSONB, arrays)
- MongoDB — doesn't fit our relational data model


## Consequences
### Positive
- Strong ACID compliance
- Excellent JSON support via JSONB
### Negative
- Schema migrations required for changes

The next time any agent works on database-related code, it queries .archcore/ and finds this decision. You do not have to repeat that PostgreSQL is the standard.

Decisions rarely stand alone. They produce rules, and rules produce guides:

use-postgres.adr.md
  └── related → migration-format.rule.md
                  └── related → run-migrations.guide.md

The ADR records why PostgreSQL. The rule defines how to write migrations. The guide walks through the steps. Agents follow the full chain.

Define coding rules

Section titled “Define coding rules”

Your team has coding standards: error formats, naming conventions, test patterns, commit message rules. Without Archcore, you repeat these in every CLAUDE.md, .cursorrules, and agent prompt. When a standard changes, you update multiple files across multiple tools.

Create a rule document once, and every agent picks it up through MCP, whichever tool your teammates use.

---
title: API Error Response Format
status: accepted
---


## Rule


1. ALL API errors MUST return JSON with `code`, `message`, and `request_id`
2. Error codes MUST use UPPER_SNAKE_CASE
3. HTTP status codes MUST match error semantics


## Rationale


Consistent error format enables clients to handle errors programmatically
and simplifies debugging across services.


## Examples


### Good


{ "code": "USER_NOT_FOUND", "message": "No user with ID 42", "request_id": "req_abc123" }


### Bad


{ "error": "not found" }


## Enforcement


Apply to all handlers in @src/api/. Verify in integration tests.

Unlike free-text instruction files, rule documents have required sections:

  • Rule statements: imperative, unambiguous requirements
  • Rationale: why the rule exists, so agents can apply it in edge cases
  • Enforcement: where and how the rule applies

The template also adds an Examples section with good and bad patterns to follow and avoid. This structure gives agents enough context to apply a rule in cases its examples do not cover. A rule often originates from an architectural decision. Use relations to make that connection explicit.

Plan implementation work

Section titled “Plan implementation work”

You need to plan a feature build or a migration: phases, tasks, dependencies, acceptance criteria. Without Archcore, plans live in project management tools or Google Docs that agents cannot access. Every session, you re-explain what needs to happen and in what order.

Create a plan document, and agents see the full scope of work:

---
title: Migrate User Data to PostgreSQL
status: draft
---


## Goal


Move all user data from MongoDB to PostgreSQL with zero downtime.


## Tasks


### Phase 1 — Schema and Migration Scripts
- [ ] Design PostgreSQL schema for users, profiles, and sessions
- [ ] Write migration scripts with rollback support
- [ ] Set up dual-write layer in @src/db/


### Phase 2 — Shadow Reads
- [ ] Route read queries to both databases
- [ ] Compare results and log discrepancies


### Phase 3 — Cutover
- [ ] Switch primary reads to PostgreSQL
- [ ] Remove dual-write layer


## Acceptance Criteria


- All user queries return identical results from PostgreSQL
- Rollback tested and documented


## Dependencies


- Depends on: use-postgres.adr.md (database decision)
- Depends on: migration-format.rule.md (migration standards)

Plans sit between vision and implementation. Relations make the connections explicit:

auth-redesign.prd.md ←── implements ── auth-redesign.plan.md
                                              │
                                              ├── depends_on → jwt-strategy.adr.md
                                              └── depends_on → auth-rules.rule.md

You don’t have to write plans from scratch. Ask your agent:

“Create an implementation plan for the auth redesign based on our PRD”

The agent reads the PRD, structures tasks into phases, and links the plan back to its source requirements.

Build project context

Section titled “Build project context”

Multiple developers on your team use AI agents. Each agent starts fresh every session, with no memory of past decisions and no awareness of standards. Without git-native context, every developer maintains their own instruction files and knowledge stays fragmented.

The .archcore/ directory lives in your repository. Every developer who clones the repo gets the same project context. Every agent (Claude Code, Cursor, Copilot, Gemini CLI) reads from the same source through MCP.

your-project/
├── .archcore/
│   ├── auth/
│   │   ├── jwt-strategy.adr.md
│   │   └── auth-redesign.prd.md
│   ├── api/
│   │   ├── error-format.rule.md
│   │   └── rest-conventions.guide.md
│   └── onboarding-flow.task-type.md
└── src/

Every tool reads the same directory, so there is nothing to sync between tools and nothing to copy between prompt files. That directory is version-controlled with your code.

Every document you add becomes context for a future agent session. The lifecycle flows like this:

idea → prd → plan → adr → rule → guide → task-type

An idea becomes a prd with requirements. The prd produces a plan with tasks. Implementation produces adr documents for the decisions made along the way. Those decisions become rule documents. Rules get guide documents that explain how to follow them. Repeated work becomes a task-type that agents follow consistently.

Because documents are plain markdown files, they go through the same workflow as code: branch, review in a pull request, merge, and track with git log.

What’s next

Section titled “What’s next”