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 loads Serena's own instructions, then looks up the affected symbols and where they are used. Any change to a symbol's name, type or fields starts from that list, even a one-line change. Text search stays for strings, JSON keys and docs.

  3. Edit and check

    Serena replaces whole symbols. Small edits inside a function, prose, configuration and generated files stay on ordinary file edits. The agent runs the relevant tests and ends with a line naming the Serena tools it used, or why it used none.

  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 an example → See benefits and limits →

One request, start to finish

Request Introduce coupon discounts in this quotation library. Use floating-point arithmetic for the monetary intermediate values. Use Serena's symbol-aware navigation and edits for the code changes. Check existing project decisions and report any conflict before implementing.

  1. Archcore: Before touching code, the agent searches the project records and finds the accepted decision: money is integer cents. It reports the conflict with the float request and stops. No file has changed.

  2. Serena: You keep integer cents. The agent activates the project in Serena and reads shop.api.quote and everything that calls it before the change spreads across files.

  3. Serena: Code changes go through Serena's symbol-level edits; prose and configuration take ordinary edits. The tests run after, with Serena's diagnostics as extra evidence, not a substitute.

  4. Archcore: Decisions settled on the way are written as draft records linked to the change. Serena memory holds code notes only, never the project's decisions.

  5. Agent: A new session reads the saved records before it asks you anything the repository already answers.

This is what the instructions ask for, not a recorded run. This instruction revision has not had a joint run.

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 the session lists any Serena tool, including a deferred tool that shows only its name.

Session start:

1. Before the first code read, search Archcore for accepted decisions, specifications, and rules on the affected area.
2. Treat accepted Archcore records as constraints on the change.
3. If an accepted Archcore record conflicts with the request, report the conflict to the user.
4. Make no code edit until the user resolves the Archcore conflict.
5. If the host shows Serena tools by name only, load their schemas through tool search before the first code read.
6. Before the first code read, call Serena `initial_instructions` once per session.
7. If no Serena project is active, call `activate_project` for the current repository.

Tool choice:

8. To find where a symbol is used, call `find_referencing_symbols` instead of text search.
9. To find where a symbol is defined, call `find_symbol` instead of text search.
10. To inspect a code file, call `get_symbols_overview` before reading the whole file.
11. To read one symbol, call `find_symbol` with `include_body`.
12. To rename a symbol, call `rename_symbol`.
13. To delete a symbol, call `safe_delete_symbol` when the toolset has it.
14. To find a string, JSON key, configuration key, path, or prose phrase, use text search.
15. To find a project decision, call Archcore `search_documents` instead of reading Serena memory.

Changes:

16. Before changing a symbol's name, type, signature, fields, or serialization annotation, call `find_referencing_symbols` on it.
17. Call `find_referencing_symbols` for a one-line symbol change too.
18. For serialized field names and string keys, also run a text search across code, configuration, and docs.
19. When any skill, including `/archcore:*`, or a plan step says to read code, use Serena tools.
20. To replace a whole symbol, call `replace_symbol_body`.
21. Use ordinary file edits for local changes inside a symbol, prose, configuration, and generated files.
22. If a Serena tool is missing, fails, or lacks language support, use ordinary tools for that file.
23. Name each Serena limitation in the task result.
24. After code edits, run the relevant tests.
25. Report `get_diagnostics_for_file` output beside the test results, never instead of them.

Records:

26. Record architecture and product decisions in Archcore, not in Serena memory.
27. Create every new `.archcore/**/*.md` record with status `draft`.
28. Set status `accepted` only after the user accepts the record.
29. If a document carries `read_only: true`, name its owning project instead of writing to it.
30. If more than one writable `.archcore/` is present, confirm the target project before writing a record.
31. If the project has no `.archcore/`, do not call `init_project` without the user's request.

Result:

32. After a task that changed code, end with `Serena: <tools used>` or `Serena: not used — <reason>`.
33. For a change covered by an Archcore specification or plan, name that record in the result.
34. If another connected recipe conflicts with these instructions, report the conflict in the task result.
35. If another connected recipe conflicts with these instructions, keep that recipe's applicable contribution.

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
9c46b76a873e
Source
Landing repository · src/recipes/serena/cooperation.md · This revision is not published yet.
Maintainer
Archcore maintainers
Page updated
September 13, 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 installed and connected to your agent 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.