Skip to content

docs: retire monolithic SPEC-backend.md #372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Blackgaurd wants to merge 1 commit into
base: docs-coloc-agents-context
Choose a base branch
from
Open

docs: retire monolithic SPEC-backend.md #372

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
See @dev-docs/SPEC-backend.md for the backend spec and @dev-docs/SPEC-frontend.md for the frontend spec.
Backend docs are co-located with the code as `AGENTS.md` files under `builders/server` (start at `builders/server/AGENTS.md` for the layer map; each subpackage has its own). Claude Code auto-loads the one nearest to what you are working on, so they are not imported here. Authoring datasets/builders is documented in `builders/scripts/AGENTS.md`, and infra in `infra/AGENTS.md`.

See @dev-docs/SPEC-frontend.md for the frontend spec.

## Before writing code

Expand Down Expand Up @@ -34,7 +36,7 @@ Structure stacks by architectural layer, bottom-up:
1. Schema / data model changes
2. Business logic / service layer
3. API / interface layer
4. If there is a significant spec change: update the relevant spec file (`SPEC-backend.md` or `SPEC-frontend.md`) as the final PR
4. If there is a significant doc change: update the co-located `AGENTS.md` for the affected backend layer (or `SPEC-frontend.md` for the frontend) as the final PR

Each PR in a stack should make one logical change. It is acceptable — and sometimes desirable — for a later PR to overwrite or refine what an earlier PR did. This is intentional: the stack shows the logical progression to the final state, not just the diff.

Expand Down Expand Up @@ -72,7 +74,7 @@ Repeat steps 2–6 for each PR in the stack. See the `git-town` skill for full c

## Tech specifications

After EVERY SET of updates to the code, update the relevant spec file (@dev-docs/SPEC-backend.md or @dev-docs/SPEC-frontend.md) with what has been changed in the code.
After EVERY SET of updates to the code, update the docs for what changed. For the backend, update the nearest co-located `AGENTS.md` to the code you changed (start at `builders/server/AGENTS.md` for the layer map, but only touch it when layer boundaries change). For the frontend, update @dev-docs/SPEC-frontend.md. Keep each doc lean: per-function mechanics belong in docstrings, cross-cutting "why" belongs in the co-located `AGENTS.md`.

## Pull requests

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A service to serve and build financial time-series data. Datastream implements a **builder server** (Python/FastAPI), a **Postgres database**, a **Caddy reverse proxy** with automatic HTTPS, example builder scripts, and a **Svelte frontend**.

See the full technical specs: [backend](dev-docs/SPEC-backend.md) | [frontend](dev-docs/SPEC-frontend.md) | [sdk](dev-docs/SPEC-sdk.md)
Technical docs: backend docs live in co-located `AGENTS.md` files under [`builders/server`](builders/server/AGENTS.md); [frontend](dev-docs/SPEC-frontend.md) | [sdk](dev-docs/SPEC-sdk.md)

## Prerequisites

Expand Down
Loading
Loading