Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

# -- toolchain: builds and checks the code -----------------------------------

FROM mcr.microsoft.com/devcontainers/base:3.0.8-noble@sha256:d7c468679f45a52ad3673d06656b5bf16e488990b17216a1fa295d9e1f89d724 AS toolchain

Check warning on line 13 in .devcontainer/Dockerfile

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Use either the version tag or the digest for the image instead of both.

See more on https://sonarcloud.io/project/issues?id=MathTrail_canvas-api&issues=AaFGD88Pbbm1AbGO9_9M&open=AaFGD88Pbbm1AbGO9_9M&pullRequest=21

SHELL ["/bin/bash", "-euo", "pipefail", "-c"]

Expand Down Expand Up @@ -207,4 +207,4 @@
# once it is built, and the one thing that does — the docker daemon started by
# the docker-in-docker feature — asks for root through sudo itself.
USER vscode
RUN mkdir -p /home/vscode/.claude /home/vscode/.config/gcloud /home/vscode/.config/gh
RUN mkdir -p /home/vscode/.claude /home/vscode/.codex /home/vscode/.config/gcloud /home/vscode/.config/gh
9 changes: 8 additions & 1 deletion .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,17 @@
"mounts": [
// Claude Code login and settings survive container rebuilds.
"source=canvas-api-claude,target=/home/vscode/.claude,type=volume",
// Codex's ChatGPT sign-in, settings and chat history: its default home, kept the same way.
"source=canvas-api-codex,target=/home/vscode/.codex,type=volume",
// The Google sign-in survives them too: the credentials Terraform reads live here.
"source=canvas-api-gcloud,target=/home/vscode/.config/gcloud,type=volume",
// And the GitHub one, so that `gh auth login` is answered once rather than once
// per rebuild.
"source=canvas-api-gh,target=/home/vscode/.config/gh,type=volume"
],
"containerEnv": {
// Tells a Claude session it runs in here, the one place it may work.
// Tells an agent's session, Claude's or Codex's, that it runs in here, the one place
// it may work.
"MATHTRAIL_DEVCONTAINER": "1",
"CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
"DISABLE_AUTOUPDATER": "1"
Expand All @@ -57,6 +60,10 @@
// Exact versions; the Claude Code extension matches CLAUDE_CODE_VERSION.
"extensions": [
"anthropic.claude-code@2.1.280",
// OpenAI's coding agent, signed in with a ChatGPT plan. It reads AGENTS.md,
// which sends it to the same rules as Claude. The extension brings its own
// CLI and sandbox, so the image installs nothing for it.
"openai.chatgpt@26.1007.21434",
"golang.go@0.56.1",
"redhat.vscode-yaml@1.24.0",
"nefrob.vscode-just-syntax@0.10.2",
Expand Down
9 changes: 9 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# AGENTS.md

The working rules of this repository are in [CLAUDE.md](CLAUDE.md), and they bind every coding agent, not only Claude Code. Read it in full before any work and follow it as written: what it asks of Claude, it asks of you. It stays the one copy of the rules; this file only says what stands in for the parts that are Claude Code's own:

- **The cloud-session exception to "Devcontainer only"** is for a cloud session of Claude Code. A Codex session that does not see `MATHTRAIL_DEVCONTAINER=1` stops before its first edit, as that rule says.
- **The review before a change is called done.** `/code-review high` is a Claude Code command, and you cannot run it; Codex's `/review` stands in for it, started by the author. Everything else in that rule holds as written: prepare the clean copy and run the checks in it, then stop and ask the author to run `/review` there; verify and handle its findings as the rule says, with at most the one second round it allows. Until a review has run, the report says that it did not.
- **A live run's narrow permission.** Claude Code gets it in `.claude/settings.local.json`. Under Codex the author approves each of the run's commands once, as it comes, never for the rest of the session, so nothing approved outlives the run; do not ask for a looser sandbox or approval mode for it.
- **A live run's report** names its roles as they were: what the author did and what Codex did.
- **Memory.** Claude Code's memory is not shared with you. What has to outlive a session goes into the repository's documents, as CLAUDE.md says.
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Project context lives in these files, not in chat history.
Each tool's exact version is pinned directly where it is installed — as an `ARG` in
`.devcontainer/Dockerfile`, as a literal in `devcontainer.json`. No separate versions file,
no checksum verification.
- **Language.** Code, every comment in code and config files (Go, TS, SQL, protobuf, YAML, HCL, Dockerfile, justfile, `.env.example`, …), `CLAUDE.md`, `README.md`, `CONTRIBUTING.md` and `SECURITY.md`, the texts of the UI, the hints the child sees and the model's prompts are in English (R02).
- **Language.** Code, every comment in code and config files (Go, TS, SQL, protobuf, YAML, HCL, Dockerfile, justfile, `.env.example`, …), `CLAUDE.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md` and `SECURITY.md`, the texts of the UI, the hints the child sees and the model's prompts are in English (R02).
- RUN.md and every document under `docs/` are in Russian (R25).
- Reports to the author in chat are in Russian.
- A comment, and any text a person reads from code or config — a description, an error message, a test's name — gives its reason in its own words. It cites no decision, task or section of the documents: no `(R58)`, `(T11)`, `(spec 15.3)`, `(RUN.md, rule 13)`. The documents do not outlive the code.
Expand Down Expand Up @@ -317,6 +317,7 @@ Inside the container:
- To change a version: edit the literal everywhere it appears (Dockerfile, `devcontainer.json` for Docker or the Claude Code extension), rebuild the container. The Claude Code CLI and its editor extension are one version in two files, so `just claude-update` raises both at once — with a version, or to the newest published one — and prints what it changed. Terraform is pinned twice as well: `ARG TERRAFORM_VERSION` and `required_version` in `infra/terraform/versions.tf`, which refuses any other. Its providers and `.terraform.lock.hcl` are raised by hand too, `terraform providers lock -platform=linux_amd64 -platform=linux_arm64`, since Dependabot would lock them with a Terraform of its own (R56).
- **Container marker.** `MATHTRAIL_DEVCONTAINER=1` is set only inside the container. A session that does not see it is on the host and must stop, unless it is a cloud session the author started (see "Devcontainer only").
- **Claude Code.** Its config lives in the `canvas-api-claude` volume, so the login survives rebuilds. Auto-update is off; the version is pinned.
- **Codex.** OpenAI's coding agent works here too, as a VS Code extension pinned in `devcontainer.json`, signed in with the author's ChatGPT plan; the version is pinned, so VS Code does not update it. The extension carries its own CLI and sandbox, which keep a command's writes to the workspace and the command off the network until the author approves more. Reading is not confined: like Claude, Codex can read the whole container, the credential volumes and a local `.env` included, and what it reads goes to OpenAI. Its home, `~/.codex`, lives in the `canvas-api-codex` volume. It reads `AGENTS.md`, which sends it to this file: the rules are kept once, here (R69).
- **`gh`.** What a change looks like on github.com is otherwise invisible from in here, and two parts of it are asked for by name: the alerts of the code scan, which a task closes before the next one starts, and whether the delivery that carried the change ran. `gh auth login` is answered once: the credentials live in the `canvas-api-gh` volume, as gcloud's live in `canvas-api-gcloud`, where Terraform reads them.
- **Ports.** 8080 (the API) and 5173 (Vite's dev server for the SPA) are forwarded to the host.
- **Just recipes.** `just --list` shows all of them.
Expand Down
2 changes: 1 addition & 1 deletion RUN.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@

## Таблица 3. Вопросы автору без ответа

Собраны 2026-10-14 из «Открыто» задач T00–T11. Открытые вопросы документов — Т- (spec 20), О- (product 15.2) и П- (privacy 12) — живут в своих разделах. Те, что касаются E2, решают его задачи: Т-1 — T61, Т-16 — T67, Т-5 — T76; остальные — при разбиении E15.
Собраны 2026-10-14 из «Открыто» задач T00–T11. Открытые вопросы документов — Т- (spec 20), О- (product 15.2) и П- (privacy 12) — живут в своих разделах. Те, что касаются E2, решают его задачи: Т-1 — T61, Т-16 — T67, Т-5 — T76, П-11 — T72, до первого образца в `samples/`; остальные — при разбиении E15.

| ID | Вопрос | Откуда | Предлагаю |
|---|---|---|---|
Expand Down
Loading