Skip to content

docs: split shared dev guidelines from personal claude instructions - #9640

Merged
koenvanderveen merged 1 commit into
devfrom
koen/organise-claude-instructions
Nov 18, 2026
Merged

koenvanderveen merged 1 commit into
devfrom
koen/organise-claude-instructions

Conversation

@koenvanderveen

Copy link
Copy Markdown
Collaborator

Summary

  • When Claude Code works in this repo, it previously read a CLAUDE.md that each of us kept for ourselves and that git ignored. Now a shared, checked-in CLAUDE.md gives the commands, the two modes of running PySyft (DO and DS, or an enclave), and the workspace packages, and it imports the guidelines. Personal instructions, such as credentials, go in a CLAUDE.local.md that git ignores.
  • When we write or review code, the rules were previously spread over the personal CLAUDE.md, the syft-pr-review skill and CONTRIBUTING.md, and they disagreed in places. Now the code rules live in dev-guidelines/guidelines.md, and the rules for writing about code live in dev-guidelines/language.md. CLAUDE.md, syft-pr-review, open-pr and CONTRIBUTING.md all point there.
  • For everyone opening a PR: the PR template previously asked for a summary, changes, testing and the Asana task. Now it asks for a summary per use case, a 🟢/🟠/🔴 rating of the PR against dev-guidelines/guidelines.md, and a security note, plus testing and the Asana task. CONTRIBUTING.md describes this format and says every PR must follow it.
  • When Claude needs detail on sync, peers, datasets or jobs, it previously had all of it in CLAUDE.md. Now it reads dev-guidelines/architecture/<topic>.md, and CLAUDE.md says when to read each file. sync-flow.md is new: it describes one sync pass as the code in syft/sync/ runs it.
  • When syft-pr-review writes a review, it now rates the PR against the guidelines in three short lines under its summary, and it takes its code standards from dev-guidelines/guidelines.md instead of its own list.
  • The new open-pr skill opens a PR in this format: it runs pre-commit, writes a conventional-commit title, and fills in the template.

Guidelines

High level

  • 🟢 Split: low confidence that this PR should be split. Every change moves shared instructions into the new layout; only the PR template change could go on its own.
  • 🟢 Size: moves the shared Claude instructions and coding rules into checked-in files, and makes PRs follow the PR report format.

Mid level

  • 🟢 User-facing code
  • 🟢 Error handling
  • 🟢 State versioning
  • 🟢 Function structure
  • 🟢 Tests

Low level

  • 🟢 Naming
  • 🟢 Code style

Security

No change.

Testing

Asana task

Check in CLAUDE.md, move code and language rules to dev-guidelines/, add the open-pr skill, and make the PR template follow the PR report format.
@koenvanderveen
koenvanderveen merged commit 7dc0651 into dev Nov 18, 2026
22 checks passed
@koenvanderveen
koenvanderveen deleted the koen/organise-claude-instructions branch November 18, 2026 13:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant