bcgov / bcgov/quickstart-openshift

feat: add tailored AGENTS.md instruction file for AI coding tools

Open
#2,792 0 comments 0 reactions 1 assignee Claimed by @DerekRoberts View on GitHub
Dominant language
TypeScript
Stars
32
Forks
10
Avg merge
1h 26m
Merged PRs (30d)
23

Description

## Summary

Modern AI coding tools (Claude Code, Cursor, Copilot, Antigravity, Aider) automatically read root instruction files (`AGENTS.md` / `CLAUDE.md`) on repository startup without requiring any manual developer configuration or setup scripts.

Adding a tailored `AGENTS.md` to `bcgov/quickstart-openshift` will ensure that any AI agent working on a repository instantiated from this template immediately inherits the technical rules, architecture conventions, and quality gates of the stack out of the box.

## Proposed `AGENTS.md` Content & Specification

The `AGENTS.md` file should provide explicit, non-ambiguous guidance tailored to the `quickstart-openshift` stack:

### 1. Stack & Directory Architecture
* **Backend**: NestJS (TypeScript) in `backend/`.
* **Frontend**: TypeScript / Caddy in `frontend/`.
* **Database & Migrations**: PostgreSQL/PostGIS. All schema changes **must** be authored as Flyway SQL scripts under `migrations/sql/`.
* **Infrastructure**: OpenShift manifests and GitHub Actions workflows under `.github/`.

### 2. Code Quality & Guardrails
* **TypeScript Strictness**: Enforce strict typing. No implicit `any` or `@ts-ignore` suppressions.
* **Secret Safety**: Strictly forbid committing `.env`, `application.properties`, or hardcoded credentials.
* **Commit Conventions**: Enforce Conventional Commits (`feat:`, `fix:`, `chore:`).
* **Dependency Safety**: Bypassing peer dependencies (`--legacy-peer-deps`) is strictly prohibited.

### 3. Verification & Execution Commands
* **Local Stack**: `docker compose up -d`
* **Migrations**: Handled via `migrations` Flyway container.
* **Testing**: Run containerized tests (`docker compose exec backend npm test`).

## Value
* **Zero developer setup**: Agents automatically load the file on repository open.
* **Prevents AI hallucinations**: Guides agents to use Flyway SQL migrations instead of inline ORM sync, enforces TypeScript strictness, and prevents secret leaks.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.