Skip to content

Add best practices to AGENTS.md: env configuration and testing guidelines#835

Merged
pyramation merged 1 commit intomainfrom
devin/1773716867-agents-best-practices
Mar 17, 2026
Merged

Add best practices to AGENTS.md: env configuration and testing guidelines#835
pyramation merged 1 commit intomainfrom
devin/1773716867-agents-best-practices

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

Summary

Adds a Best Practices section to the root AGENTS.md with two subsections:

  1. Environment Configuration — Documents the unified env config system and which package to import depending on where you're working (@pgpmjs/env for PGPM packages, @constructive-io/graphql-env for GraphQL/Constructive packages, pg-env for postgres tools). Includes a good/bad code example.

  2. Testing — Documents the four-layer testing framework hierarchy (pgsql-testgraphile-test@constructive-io/graphql-test@constructive-io/graphql-server-test), the required beforeEach/afterEach hook pattern, and a list of anti-patterns to avoid (manual pg.Pool creation, using pg-cache in tests, skipping hooks, etc.).

This is a companion to constructive-skills#57 which adds detailed constructive-env and constructive-testing skills.

Review & Testing Checklist for Human

  • Verify package import paths are correct — confirm that @pgpmjs/env, @constructive-io/graphql-env, pg-env, pgsql-test, graphile-test, @constructive-io/graphql-test, and @constructive-io/graphql-server-test are the actual importable package names in this monorepo
  • Verify the test hooks boilerplate matches the canonical pattern used across existing tests (ordering of beforeEach/afterEach for pg vs db)
  • Check that the "which package to import" guidance (pgpm/*@pgpmjs/env, graphql/*@constructive-io/graphql-env, postgres/*pg-env) matches actual usage across the monorepo — particularly whether pg-env is the right recommendation for postgres/* packages

Notes

  • Documentation-only change — no code modified, no CI impact expected.
  • The anti-patterns listed (manual pg.Pool, pg-cache in tests, manual DB create/drop) were identified from actual instances found in the codebase (e.g., postgres/introspectron/__tests__/introspect.test.ts).

Link to Devin session: https://app.devin.ai/sessions/534e3c7cdabd4b70afea0c91e615ef0b
Requested by: @pyramation

- Environment Configuration: documents the unified env config system
  (@pgpmjs/env and @constructive-io/graphql-env) with which-to-import guide
- Testing: documents the framework hierarchy (pgsql-test → graphile-test →
  graphql-test → server-test), required beforeEach/afterEach hooks, and
  anti-patterns to avoid (manual pg.Pool, pg-cache in tests, etc.)
@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@pyramation pyramation merged commit fe84488 into main Mar 17, 2026
43 checks passed
@pyramation pyramation deleted the devin/1773716867-agents-best-practices branch March 17, 2026 06:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant