archcore
Star Install
Menu
Experimental

Serena + Archcore

Check code changes against project decisions. Navigate and edit code by symbol with Serena.

How Serena + Archcore work together

Serena + Archcore connects a code change to the decisions that constrain it. Serena finds the symbols and references the change touches, and edits them at the symbol level. Archcore supplies the accepted decisions, rules and specifications before the work starts, and keeps new decisions in Git afterwards.

For example, a request to rename a payment interface reaches every call site through Serena’s reference list. If an accepted rule pins that interface for a published contract, the agent reports the conflict and stops the affected work until you decide. You keep the rule or you change it, and the change follows.

The instructions also separate the two kinds of memory. Serena memory holds code notes for its own use; architecture and product decisions go to Archcore as draft records for your acceptance. For Serena’s own commands, language support and installation, see the Serena project.

Archcore ↗
Keeps project decisions, rules and specifications in Git so your agent can check a change against them.
Serena ↗
Finds symbols and their references in the code, and applies edits at the symbol level.

From a code request to a recorded decision

The instructions ask your agent to:

  1. Read the decisions first

    Before changing code, the agent searches Archcore for accepted decisions, rules and specifications that cover the area. An accepted decision is treated as a constraint on the change.

  2. Look up the symbols

    The agent activates your project in Serena, then inspects the affected symbols and their references. A rename, a move or a cross-file refactor starts from that reference list rather than from a text search.

  3. Edit and check

    Serena applies symbol-level edits where it can model the change safely. Prose, configuration and generated files stay on ordinary file edits. The agent then runs the relevant tests and reports diagnostics beside them.

  4. Record what was settled

    New architectural decisions are written to Archcore as draft records, linked to the change. Accepting a record is a separate step that needs your approval.

  5. Continue in the next session

    A later session reads the saved records before repeating questions. Serena memory stays available for code notes, but it does not hold the project's decisions.

Serena keeps the code-level view. Archcore keeps the decisions, and the instructions ask the agent to check one against the other.

See benefits and limits →

Connect the two tools

1. Install Archcore and Serena

Install Archcore and Serena in the agent you use for this project.

2. Add instructions

CLAUDE.md / AGENTS.md / GEMINI.md 
### Archcore + Serena

Applies when Archcore and Serena are both available.

1. Use Archcore for project knowledge, decisions, specifications, plans, and traceability. Use Serena for symbol-aware code navigation, reference lookup, diagnostics, and semantic edits.
2. Before changing code, search Archcore for accepted decisions, relevant specifications, and prior records. Treat accepted decisions as constraints.
3. Activate the project in Serena before querying symbols. Use Serena to inspect relevant symbols and references before a cross-file change, rename, move, or refactor.
4. Do not use Serena memory as the source of truth for architecture or product decisions. Record durable decisions in Archcore.
5. When an Archcore specification or accepted decision conflicts with the requested implementation, report the conflict and stop for the user's decision.
6. When the user names an `/archcore:*` command or Archcore skill, load and follow that skill's instructions before starting implementation work.
7. After an Archcore planning or documentation command completes, use Serena to validate the affected code structure, dependencies, and references when useful.
8. For a change covered by an Archcore specification or plan, preserve the link between the code change and its governing record in the task result.
9. Use Serena's symbol-aware edits for code symbols when available. Use ordinary file edits for prose, configuration, generated files, or changes Serena cannot model safely.
10. Run the relevant tests after semantic edits. Use Serena diagnostics as additional evidence, not as a replacement for tests.
11. If Serena is unavailable or cannot analyze a language or file, continue with normal repository tools and name that limitation in the result.
12. Do not call `init_project` merely because Archcore is present. If no `.archcore/` exists, work from repository files unless the user asks to initialize Archcore.
13. Create new Archcore records with `status: draft`. Set `status: accepted` only after the user explicitly accepts the record.
14. If more than one writable `.archcore/` directory exists, ask the user which project owns the new record before writing it.

3. Check in a new session

Start a new session in this project and ask your agent:

Confirm you can use Archcore and Serena, and have read this project’s cooperation instructions.

If the agent reports a missing tool or instruction file, finish that setup before starting work.

Benefits & limits

Change code with its constraints in view.

The agent brings accepted decisions into a code change before it starts, and works from real symbol references instead of matched strings. Decisions worth keeping end up in the repository.

Start with Archcore.

Keep your project decisions ready for the next task.

Install Archcore →See how it works

Serena + Archcore

Source & verification

Category
Code navigation
Instruction revision
e9c1d378e04d
Source
Landing repository · src/recipes/serena/cooperation.md · This revision is not published yet.
Maintainer
Archcore maintainers
Page updated
September 12, 2026

Verification

No joint run has been recorded for this instruction revision.

  • This instruction text has no linked verification record, so the pairing is experimental.
  • Serena is not installed by this recipe. It has to be present and its project activated already.
  • Symbol-aware navigation depends on Serena's language support. Where a language or file is unsupported, the agent falls back to ordinary repository tools.
  • Serena diagnostics are additional evidence. They do not replace running the tests.
  • Setup steps are written for the common instruction files and checked on no host.
  • This pair only. Two working pairs do not make a working triple.

Update or disconnect

To update, review changes to the instructions before replacing your copy. To disconnect, remove the added instructions from your project file. Both tools and their documents stay in place.