Imported from sdsc-ordes/agents (AGENTS.md). Install upstream with npx skills add sdsc-ordes/agents. Copyright stays with the author.

Agent Instructions

Guidelines for AI agents working in the Swiss Data Science Center (SDSC) codebase.

General values

• Explicit over Implicit: Code should be readable and obvious. Avoid "magic" logic.
• Robustness: Prioritize error handling and edge cases over happy-path-only code.
• Statelessness: Avoid mutable global state. Prefer pure functions.
• Testability: Code must be designed to be easily tested (dependency injection, small units).
• Conciseness: Prefer self-documenting code and terse documentation without filler.
• Modularity: Aim for components with low coupling and high cohesion.

Project structure

When creating directories, default to our standard project structure, unless the project has an existing alternative.

• docs: All documentation-related files.
• examples: Examples showing how to use the software.
• external: Imported third party resources.
• src: Where your source code lives.
• tools: All configurations and scripts which are not part of the source.
  • configs: config for tools (e.g. formatters, linters).
  • images: Containerfile definitions of OCI images.
  • just: just modules (e.g. image.just).
  • nix: Nix flake and code.
  • ci: CI related tooling/scripts.
  • scripts: Additional scripts.

Toolchain

Use the project's existing toolchain when available. Otherwise, default to the following.

• just as command runner.
• nix flakes for devShells.
• podman for OCI images.
• prek as git-hook manager.
• vendir to manage external dependencies.
• For python components: uv, ruff.
• For javascript components: pnpm.

Rules by Topic

These general rules define our high level development practices. For framework-specific recommendations, refer to specific skills.

Testing

• Apply the cheapest verification (static analysis / type checking) to all code; treat its failures as build failures.
• Use property-based tests when relevant: generate many inputs and assert invariants rather than hand-picked cases.
• Reserve example/unit tests for simple pure functions and for pinning regressions a stronger test uncovers.

Dependencies

• Default to a proven, well-maintained dependency for solved, non-core problems.
• Upgrade policy is to pin to the major (breaking) boundary by default.
• Reproducibility comes from a committed lockfile for every deployable.

Documentation

• Document why, not what. The code shows what; comments explain why.
• Use the language's documentation convention (doc comments / docstrings) at module level and on every public type and function.
• Describe functions in the imperative mood ("Send payload", not "Sends a payload").
• ASCII-only preferred in code and documentation.

Validation Workflow

• Validation commands should be defined by the task runner (e.g. make or just).
• If no command is provided, always run tools using the project configuration.
• Run validation after every code change.

Key Reminders

1. Run validation after changes - never skip
2. Use project recipes when available, not raw commands.
3. Whenever making major code changes, make sure to update outdated documentation and tests.

Review Checklist

When reviewing code:

• Tests added/updated for new functionality
• Error messages are actionable
• No hardcoded paths or credentials
• Documentation updated (README, docstrings, comment-based help)
• Backward compatibility maintained

This file is optimized for both AI agents and human contributors. When in doubt, prioritize clarity and maintainability over cleverness.