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 as whole symbols. Archcore gives the agent the accepted decisions, rules and specs before work starts, and keeps new decisions in Git after.

Say you ask to rename a payment interface. Serena’s reference list reaches every call site. If an accepted rule pins that interface for a published contract, the agent reports the conflict and waits for you to keep or change the rule.

Serena memory holds code notes; decisions go to Archcore as drafts you accept. Commands, language support and installation are on the Serena project page.

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 specs that cover the area. An accepted decision constrains the change.

  2. Find the symbols, then edit

    Serena lists the affected symbols and every place that uses them, and edits them as whole symbols. The agent runs the relevant tests after.

  3. Record what was settled

    New decisions go to Archcore as draft records for you to accept. Serena memory keeps code notes only, so the next session reads decisions from the repository.

Serena sees the code, Archcore keeps the decisions, and the agent checks 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 for the code changes, and report any conflict with project decisions first.

  1. Archcore: The agent finds the accepted integer-cents decision, reports the conflict with the float request and stops before any file changes.

  2. Serena: You keep integer cents, and the agent reads shop.api.quote and all its callers in Serena.

  3. Serena: Code changes go through Serena's symbol edits, then the tests run.

  4. Archcore: Decisions settled on the way become draft records linked to the change.

  5. Agent: A new session reads those 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 knows the accepted decisions before it starts, and works from real symbol references instead of matched strings.

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.

  • No verification record is linked to this instruction text, so the pairing is experimental.
  • Serena must already be installed and connected. Where it does not support a language, the agent falls back to ordinary tools.
  • Serena diagnostics do not replace running the tests.

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.