Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (57 loc) · 5.29 KB

AGENTS.md

File metadata and controls

77 lines (57 loc) · 5.29 KB
Raw

Ferry Agent Guidance

Scope

These instructions apply to the entire repository. More specific AGENTS.md files may add local guidance but must not weaken the public-repository rules below.

Ferry is an open-source project. Treat every tracked file, diff, issue excerpt, test fixture, generated asset, and example as public from the moment it is created.

Public-repository hygiene

  • Never add personal information, including private names, email addresses, phone numbers, locations, usernames, home-directory paths, device names, biographies, or details inferred about maintainers or contributors.
  • Never add credentials or authentication material, including API keys, access tokens, passwords, cookies, session data, private keys, signing secrets, recovery codes, credential-bearing connection strings, or unredacted secret-manager references.
  • Never add private infrastructure details, customer or production data, internal hostnames, non-public URLs, captured payloads, database dumps, or real operational logs.
  • Never add local agent transcripts, caches, histories, authentication state, editor settings, or machine-specific configuration.
  • Use synthetic examples such as evt_123, order_123, example.com, 127.0.0.1, and explicit placeholders such as ${FERRY_DATABASE_URL}.
  • Keep examples deterministic and obviously fictional. Do not base fixtures on real people, organizations, systems, or incidents.
  • Avoid absolute local filesystem paths in committed files. Repository-relative paths belong in documentation and configuration examples.
  • Describe choices in terms of Ferry's product and engineering requirements, not an individual's preferences or personal context.

If sensitive material is discovered, do not reproduce it in documentation, patches, test output, or chat summaries. Identify only the affected repository path, remove the material from the working change, and state that exposed credentials must be revoked or rotated. Rewriting published Git history requires explicit maintainer coordination.

Agent and skill files

Project-level agent guidance and reusable skills are welcome when they are useful to Ferry and safe to publish.

  • Keep AGENTS.md, CLAUDE.md, .codex/skills/, and .claude/skills/ project-centered and tool-neutral where practical.
  • Every tracked skill must be reusable by any contributor and must contain no personal paths, private endpoints, local tool state, or credentials.
  • Do not commit .codex or .claude session data, authentication, histories, caches, or personal settings.
  • Prefer one source of truth and short tool-specific pointers over duplicated instructions that can drift.

Project definition

Ferry is a backend-only, Postgres-native transactional outbox relay written in Go. Its promise is reliable delivery for events committed to PostgreSQL.

Version-one constraints:

  • PostgreSQL is the durable source of truth.
  • Delivery uses at-least-once request-attempt semantics with stable event and delivery IDs.
  • Destinations must be idempotent; Ferry does not claim end-to-end exactly-once processing.
  • The initial service is single-node and uses PostgreSQL coordination.
  • HTTP webhooks are the first destination type.
  • Kafka, Redis, NATS, a workflow engine, a frontend dashboard, and multi-region clustering are not version-one dependencies or goals.
  • Runtime features remain planned until working code and tests exist.

Architecture sources

  • README.md is the product-facing entry point.
  • docs/product/vision.md defines users, scope, non-goals, and success criteria.
  • docs/architecture/overview.md links the current architecture sources.
  • docs/architecture/data-model.md defines proposed persistence boundaries and invariants.
  • docs/architecture/runtime.md defines proposed Go dependency and lifecycle boundaries.
  • docs/architecture/http-delivery.md defines the proposed webhook contract.
  • docs/adr/ records accepted and proposed architecture decisions. Do not present a proposed ADR as accepted without an explicit owner decision.
  • docs/roadmap.md defines milestone order; it is not an implementation-status checklist.

Engineering workflow

  • Inspect existing files and repository guidance before editing.
  • Preserve unrelated work in a dirty worktree.
  • Keep core packages independent of concrete infrastructure adapters.
  • Keep PostgreSQL transactions short and never hold one open during HTTP I/O.
  • Keep queues, batches, request bodies, response diagnostics, retries, and concurrency bounded.
  • Use real PostgreSQL for repository and concurrency integration tests.
  • Do not create empty packages, fake implementations, speculative commands, fake badges, benchmark claims, or production-readiness claims.
  • Update documentation when a public contract, state transition, failure boundary, or architecture decision changes.

Required validation

Before handing off a change:

  1. Review every changed file as public material.
  2. Inspect the diff for personal information, secrets, private paths, real infrastructure, and captured data.
  3. Confirm examples use synthetic identifiers and public-safe domains.
  4. Run gofmt for changed Go files.
  5. Run go test ./..., go vet ./..., and the relevant integration or failure tests when available.
  6. Run git diff --check and verify relative Markdown links.
  7. Report validation honestly, including checks that could not run.