From 7a4fbcb19c10d680f3fb347a238bca126d41185d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Hern=C3=A1ndez?= Date: Thu, 25 Jun 2026 11:50:31 +0200 Subject: [PATCH] docs: add AGENTS.md and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md is the canonical guidance file for AI agents working in this repository — covering architecture constraints, conventions, and rules. CLAUDE.md contains only `@AGENTS.md`, making Claude Code load this file automatically alongside other AI tools. Assisted-by: ClaudeCode:claude-sonnet-4-6 Signed-off-by: Alex Hernández --- AGENTS.md | 24 ++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 25 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..ceb14721b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,24 @@ +# server — Euro-Office + +@../AGENTS.md + +Guidance for Claude Code (and other AI agents) working in **server** — the Node.js backend. + +## What this repo is +The stateful backend services for Euro-Office Document Server. Forked from `ONLYOFFICE/server`. Licensed **AGPL-3.0**. + +## Architecture & Workflow +- **Async patterns:** Uses `function*` + `co` for async flows. **Do not** refactor to `async/await` unless the entire call chain is updated. Mixing patterns causes race conditions in co-editing state. +- **Storage:** All I/O must pass through the storage abstraction in `Common/sources/storage/` (`storage-base.js` + per-backend drivers `storage-fs.js` / `storage-s3.js` / `storage-az.js`). Never write directly to disk. +- **Persistence:** Database schema lives in `schema//` (one set per backend: `postgresql`, `mysql`, `mssql`, `oracle`, `dameng`), with `createdb.sql` and an `upgrade/` folder. A schema change must be applied across all backends, never mutated ad-hoc. +- **Packaging:** Uses `pkg`. Adding native modules (`.node`) requires updating `pkg` config. + +## Rules +- **Never** modify `SpellChecker/` without installing its dependencies separately — it has its own `package.json` with a native C++ dependency (`nodehun`, built via node-gyp) and is excluded from the main ESLint config. Treat it as an isolated sub-service. +- **Never** commit `.node` binaries or `pkg` artifacts. +- **Never** bypass the storage abstraction in `Common/sources/storage/`. +- **Never** change the co-editing logic in `DocService/sources/` (e.g. `DocsCoServer.js`) without running the full unit test suite (`npm run "unit tests"`). +- **Always** run `npm run code:check` before PR. + +## Findings & Long-tail +No centralized findings store exists in this repository yet. Edge-case debugging recipes and co-editing race conditions should be documented in code comments or tracked as GitHub issues until a findings store is established. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md