Agent Guide - #474
Open
ChengShi-1 wants to merge 3 commits into
Open
Conversation
pdurbin
reviewed
Aug 4, 2026
| @@ -0,0 +1,165 @@ | |||
| # Copilot instructions: dataverse-client-javascript | |||
|
|
|||
| This file is a copy of [AGENTS.md](../AGENTS.md) at the repository root, kept here because this is the path GitHub Copilot reads automatically for repository-wide chat and code-review context. Keep both in sync. | |||
Member
There was a problem hiding this comment.
Please check this out: https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/cloud-agent/get-the-best-results#adding-custom-instructions-to-your-repository
Here's a screenshot:
I think this means we can safely delete the .github/copilot-instructions.md file. No syncing! 🎉
p.s. I found those docs via https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new repository-root AGENTS.md meant to serve as the canonical “agent guide” for AI tools and contributors working in this SDK repo, documenting architecture, HTTP/auth behavior, and testing/CI workflows.
Changes:
- Introduces
AGENTS.mddescribing the SDK’s clean-architecture layering and composition-root pattern. - Documents HTTP/auth configuration patterns and common “gotchas”.
- Documents test suite structure (unit/integration/functional) and CI workflow expectations.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+46
to
+49
| - `ApiRepository`, in `src/core/infra/repositories/`, is the base class every `<Domain>Repository` extends. It exposes `doGet`, `doPost`, `doPut`, `doDelete`, thin wrappers around axios. | ||
| - `ApiConfig` is a global singleton holding the configured `dataverseApiUrl` and auth mechanism (`API_KEY`, `SESSION_COOKIE`, or `BEARER_TOKEN`), set once via `ApiConfig.init(...)`. | ||
| - Every `doGet`/`doPost` call takes an `authRequired: boolean` as an explicit argument. When `true`, `buildRequestConfig` (in `apiConfigBuilders.ts`) attaches whichever credential `ApiConfig` currently holds: an `X-Dataverse-key` header for `API_KEY`, a cookie for `SESSION_COOKIE`, or an `Authorization: Bearer` header for `BEARER_TOKEN`. When `false`, no ambient credential is attached at all, regardless of what's configured. | ||
| - Dataverse itself accepts an API key, or any equivalent token, via the `X-Dataverse-key` header or a `?key=` query parameter; either works, for any authenticated endpoint. That equivalence is why token-based access (see Preview URLs below) can be threaded through as a query param without touching the auth-mechanism plumbing at all. |
Comment on lines
+113
to
+118
| | Command | Config | Docker? | | ||
| | ------------------------------------- | ---------------------------- | -------------------------------------------- | | ||
| | `npm run test:unit` | `jest.config.unit.ts` | No: `globalSetup` is deleted for this config | | ||
| | `npm run test:integration` | `jest.config.integration.ts` | Yes, full stack | | ||
| | `npm run test:functional` | `jest.config.functional.ts` | Yes | | ||
| | `npm test` / `jest -c jest.config.ts` | base config | Yes, runs everything including unit | |
| 5. **Link the backend PR** in the "Related Dataverse PRs" field when this SDK change depends on one, the same PR the "Finding the API spec" section above points to when an endpoint isn't documented yet. | ||
| 6. **Match the existing commit-message convention**: recent history uses a `type: description` prefix (`feat: ...`, `fix: ...`, `chore(deps): ...`), even though it isn't formally enforced. | ||
|
|
||
| `deploy_pr.yml` runs three CI jobs on every PR: `test-unit`, `test-integration`, and `test-functional` (the last only after integration passes). This is the actual enforcement behind step 7 of the use-case recipe: skipping integration tests locally still means CI runs them before merge. |
|
|
||
| ## Git hygiene | ||
|
|
||
| The `.husky/pre-commit` hook runs `npm run format && npm run typecheck && npm run lint:fix && git add .`. That final `git add .` stages every modified or untracked file in the working tree, not just what got `git add`ed deliberately. Unrelated in-progress edits sitting in the working tree at commit time get swept in regardless of intent. Set aside anything that shouldn't be bundled before committing, for example with `git stash push -- <path>`, or by copying it elsewhere and restoring it after. |
ChengShi-1
added
Size: 3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it:
Adds an
AGENTS.mdat the repo root. Claude generated the initial draft as a skill, and I added notes and questions based on problems I encountered while working with it, including how to handle flaky tests and how to verify API behavior before writing new use cases.Additional guidance is welcome, especially rules that could reduce hallucinations and improve the agent’s accuracy and overall performance.
A human readable format, link for
AGENTS.md: https://github.com/IQSS/dataverse-client-javascript/blob/d90e9b009849a7c8f88543e5ef3905571d55cc1f/AGENTS.mdWhich issue(s) this PR closes:
Related Dataverse PRs:
Special notes for your reviewer:
GitHub Copilot can read for every chat and PR-review interaction in this repo by design; that's the entire reason that file exists.
Tools that natively support the
AGENTS.mdconvention (Cursor, Codex, and others converging on it) load it as ambient context automatically too. Zero prompt needed. Codex or Copilot auto-discoversAGENTS.mdat the repo root and loads it as instructions for every session in that repo.Suggestions on how to test this:
No functional code changed; this is documentation only.
Is there a release notes or changelog update needed for this change?:
No. This only adds contributor/agent documentation; it doesn't change any use case, public API, or behavior.
Additional documentation:
AGENTS.md