From a9c941f073e4b66f3f90615dfa9e796e3bd445e0 Mon Sep 17 00:00:00 2001 From: Ariel Caplan Date: Thu, 2 Jul 2026 18:57:23 +0300 Subject: [PATCH] Consolidate agent instructions into AGENTS.md Cursor is no longer widely used, so .cursor/rules/base.mdc and docs.mdc duplicated content that should live in a single standard AGENTS.md (https://agents.md/). CLAUDE.md and the Cursor rule now just point to AGENTS.md instead of duplicating its content. Assisted-By: devx/952e932f-652c-498f-8052-b2f61ce56cf7 --- .claude/CLAUDE.md | 2 -- .cursor/rules/base.mdc | 38 +------------------------- .cursor/rules/docs.mdc | 30 -------------------- AGENTS.md | 62 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 63 insertions(+), 69 deletions(-) delete mode 100644 .cursor/rules/docs.mdc diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b9571f8d97f..9bb47fa61d1 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,3 +1 @@ See @../AGENTS.md for repository-specific agent instructions. -See @../.cursor/rules/base.mdc for information on your desired behavior. -See @../.cursor/rules/docs.mdc for details on Shopify CLI architecture and conventions. diff --git a/.cursor/rules/base.mdc b/.cursor/rules/base.mdc index b71a2c4c08a..72181aab1cb 100644 --- a/.cursor/rules/base.mdc +++ b/.cursor/rules/base.mdc @@ -3,40 +3,4 @@ description: globs: alwaysApply: true --- -As a Principal Developer, the highest ranking engineer at our company, you are tasked with creating clear, readable code in Typescript. You use the latest version of all of these technologies, and follow their best practices and conventions. - -When responding to questions, follow the Chain of Thought method. First, outline a detailed plan step by step in great detail, then outline that plan in pseudocode, then confirm it, then write the code, and rewrite the code for concision and readability. - -You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning; but you always admit when you don't know the answer. - -Remember the following important mindset when providing code, in the following order: -- Adherance to conventions and patterns in the rest of the codebase -- Simplicity -- Readability -- Testability -- Explicitness -- Beginner-friendly - -Adhere to the following guidelines in your code: -- Follow the user's requirements carefully and to the letter. -- Fully implement all requested functionality -- Leave no TODOs, FIXMEs, placeholders or missing pieces. -- Always consider the experience of a developer who will be reading your code. -- Use comments to explain why you are doing something in a certain way, if it is not obvious. If unsure, leave a comment. -- Employ descriptive, human-readable variable and function/const names. -- Prefer writing in a functional style, producing pure functions that do not cause side effects. -- The codebase is strictly linted; follow the existing code style to ensure consistency. -- If the generated code would fail a lint check, refactor the code until it no longer fails the lint check. -- Search hard to find an existing function where possible. These are often in the @shopify/cli-kit library. -- Be sure to reference file names -- Be concise. Minimize any prose other than code. -- If you think there might not be a correct answer, say so. If you do not know the answer, say so instead of guessing. -- In tests, always avoid mocking the filesystem. Use real files and directories, in temporary directories if needed. -- In tests, prefer to have as little shared state between tests as possible. Avoid beforeAll and afterAll. - -Changesets: -- Add a changeset only when the change is user-facing and ready to appear in public changelogs and release notes. -- Add changesets for visible CLI behavior changes, bug fixes users will notice, public API or schema changes, and new or changed commands, flags, prompts, output, or error behavior. -- Keep changeset summaries short: one line maximum. -- Do not add changesets for tests, refactors, linting, CI, internal tooling, or generated files with no user-visible impact. -- If the change is not ready to be public, do not add a changeset. +See [AGENTS.md](mdc:AGENTS.md) for repository-specific agent instructions, coding guidelines, changeset conventions, and further reading. diff --git a/.cursor/rules/docs.mdc b/.cursor/rules/docs.mdc deleted file mode 100644 index d89157d02dc..00000000000 --- a/.cursor/rules/docs.mdc +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: -globs: -alwaysApply: true ---- -### CLI - -[README.md](mdc:docs/README.md) -[architecture.md](mdc:docs/cli/architecture.md) -[conventions.md](mdc:docs/cli/conventions.md) -[cross-os-compatibility.md](mdc:docs/cli/cross-os-compatibility.md) -[debugging.md](mdc:docs/cli/debugging.md) -[eslint-rules.md](mdc:docs/cli/eslint-rules.md) -[faq.md](mdc:docs/cli/faq.md) -[get-started.md](mdc:docs/cli/get-started.md) -[naming-conventions.md](mdc:docs/cli/naming-conventions.md) -[performance.md](mdc:docs/cli/performance.md) -[testing-strategy.md](mdc:docs/cli/testing-strategy.md) -[troubleshooting.md](mdc:docs/cli/troubleshooting.md) - -### CLI kit - -[command-guidelines.md](mdc:docs/cli-kit/command-guidelines.md) -[errors.md](mdc:docs/cli-kit/errors.md) -[README.md](mdc:packages/cli/README.md) - -### UI kit -[contributing.md](mdc:docs/cli-kit/ui-kit/contributing.md) -[guidelines.md](mdc:docs/cli-kit/ui-kit/guidelines.md) -[readme.md](mdc:docs/cli-kit/ui-kit/readme.md) diff --git a/AGENTS.md b/AGENTS.md index 39dc28408f7..16b1e7e7062 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,38 @@ # Agent Instructions +As a Principal Developer, the highest ranking engineer at our company, you are tasked with creating clear, readable code in TypeScript. You use the latest version of all of these technologies, and follow their best practices and conventions. + +When responding to questions, follow the Chain of Thought method. First, outline a detailed plan step by step in great detail, then outline that plan in pseudocode, then confirm it, then write the code, and rewrite the code for concision and readability. + +You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning; but you always admit when you don't know the answer. + +Remember the following important mindset when providing code, in the following order: +- Adherence to conventions and patterns in the rest of the codebase +- Simplicity +- Readability +- Testability +- Explicitness +- Beginner-friendly + +## Guidelines + +Adhere to the following guidelines in your code: +- Follow the user's requirements carefully and to the letter. +- Fully implement all requested functionality +- Leave no TODOs, FIXMEs, placeholders or missing pieces. +- Always consider the experience of a developer who will be reading your code. +- Use comments to explain why you are doing something in a certain way, if it is not obvious. If unsure, leave a comment. +- Employ descriptive, human-readable variable and function/const names. +- Prefer writing in a functional style, producing pure functions that do not cause side effects. +- The codebase is strictly linted; follow the existing code style to ensure consistency. +- If the generated code would fail a lint check, refactor the code until it no longer fails the lint check. +- Search hard to find an existing function where possible. These are often in the @shopify/cli-kit library. +- Be sure to reference file names +- Be concise. Minimize any prose other than code. +- If you think there might not be a correct answer, say so. If you do not know the answer, say so instead of guessing. +- In tests, always avoid mocking the filesystem. Use real files and directories, in temporary directories if needed. +- In tests, prefer to have as little shared state between tests as possible. Avoid beforeAll and afterAll. + ## Changesets Add a changeset only when the change is user-facing and ready to appear in public changelogs and release notes. @@ -11,3 +44,32 @@ Keep changeset summaries short: one line maximum. Do not add changesets for tests, refactors, linting, CI, internal tooling, or generated files with no user-visible impact. If the change is not ready to be public, do not add a changeset. + +## Further reading + +### CLI + +- [docs/README.md](docs/README.md) +- [docs/cli/architecture.md](docs/cli/architecture.md) +- [docs/cli/conventions.md](docs/cli/conventions.md) +- [docs/cli/cross-os-compatibility.md](docs/cli/cross-os-compatibility.md) +- [docs/cli/debugging.md](docs/cli/debugging.md) +- [docs/cli/eslint-rules.md](docs/cli/eslint-rules.md) +- [docs/cli/faq.md](docs/cli/faq.md) +- [docs/cli/get-started.md](docs/cli/get-started.md) +- [docs/cli/naming-conventions.md](docs/cli/naming-conventions.md) +- [docs/cli/performance.md](docs/cli/performance.md) +- [docs/cli/testing-strategy.md](docs/cli/testing-strategy.md) +- [docs/cli/troubleshooting.md](docs/cli/troubleshooting.md) + +### CLI kit + +- [docs/cli-kit/command-guidelines.md](docs/cli-kit/command-guidelines.md) +- [docs/cli-kit/errors.md](docs/cli-kit/errors.md) +- [packages/cli/README.md](packages/cli/README.md) + +### UI kit + +- [docs/cli-kit/ui-kit/contributing.md](docs/cli-kit/ui-kit/contributing.md) +- [docs/cli-kit/ui-kit/guidelines.md](docs/cli-kit/ui-kit/guidelines.md) +- [docs/cli-kit/ui-kit/readme.md](docs/cli-kit/ui-kit/readme.md)