From 486e519a2d0253eb2acabc22ca43ed0bf6c1d185 Mon Sep 17 00:00:00 2001 From: Walter Date: Sat, 18 Apr 2026 12:21:01 +0800 Subject: [PATCH] Add AGENTS.md files for documentation review guidelines --- AGENTS.md | 60 ++++++++++++++++++++++++++++++++++++++++++++ docs/AGENTS.md | 38 ++++++++++++++++++++++++++++ docusaurus.config.js | 1 + 3 files changed, 99 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ffcf644 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# AGENTS.md + +## Scope + +- This file defines the repository-wide default rules. +- `docs/AGENTS.md` adds rules for the current-version docs under `docs/**`; the closer file takes precedence. +- If a historical version or another subtree needs different behavior, add an `AGENTS.md` or `AGENTS.override.md` in that directory. + +## Repository Map + +- Current-version docs live in `docs/`. +- Historical docs live in `versioned_docs/`. +- The current sidebar lives in `sidebars.js`. +- Historical sidebars live in `versioned_sidebars/`. +- Site configuration lives in `docusaurus.config.js`. +- Common build validation: `npm run build`. + +## Default Review Mode + +- When the user asks for a review, default to document review mode. +- Prioritize issues that can mislead readers, break navigation, break anchors, break the build, or introduce factual errors over broad copy-editing. +- Start from the changed scope. If a diff is available, review the diff first and avoid generalized comments on untouched areas. +- Prefer concrete findings with file and line references, and explain reader impact. +- Style preferences alone are not findings. Do not rewrite already-clear text just to make it sound more polished. +- If no issues are found, explicitly say `No findings` and note any remaining risks or unverified areas. + +## Severity + +- `P1`: Breaks links, anchors, navigation, or builds, or directly misleads users with incorrect steps, commands, parameters, prerequisites, capability claims, or compatibility guidance. +- `P2`: Does not fail immediately, but creates clear confusion or mild misinformation, such as inconsistent terminology, broken heading hierarchy, drifted paths or UI labels, or mismatches between page content and navigation labels. +- `P3`: Typos, grammar issues, minor ambiguity, or other small fixes that do not change the meaning. +- Aesthetic preferences, phrasing taste, or stylistic rewrites alone are not findings. + +## Review Output Contract + +- Keep one finding focused on one issue. +- Each finding should include the location, the problem itself, and the user impact. Add a verification hint when it is helpful. +- Unless the user explicitly asks for it, do not propose a full-page rewrite. Prefer the smallest actionable correction. +- Do not guess about product behavior, defaults, limits, compatibility, or connector capabilities. Mark them as `unverified` or `needs product/implementation confirmation` instead. +- For inline comments or review-pane feedback, keep the scope tight and target the changed lines first. + +## Content Accuracy + +- Do not casually change code blocks, commands, parameter names, API field names, UI labels, version numbers, paths, example values, or documented limits. +- Procedure steps should include prerequisites, sequence, and an observable result. If any of the three is missing, raise it as an accuracy or executability issue. +- `versioned_docs/**` represents historical behavior. Do not silently align it with current-version behavior without evidence. +- If both current and historical docs may be affected, call out the sync scope explicitly instead of changing both by default. + +## Docusaurus Checks + +- When review touches `sidebars.js`, `versioned_sidebars/**`, front matter `id` or `slug`, cross-document links, or heading anchors, check navigation, doc IDs, anchors, and references together. +- If you are fixing rather than only reviewing: after changing links, titles, or relative paths, prefer `npm run remark:once`; after changing sidebars, doc IDs, slugs, versioned docs, or site config, run `npm run build` when feasible. + +## Connector Documentation + +- When changes touch connector or prerequisite docs such as `docs/connectors/**`, `docs/cloud/prerequisites/**`, or `versioned_docs/**/prerequisites/**`, lightly cross-check implementation or metadata sources when feasible. +- One public reference source is the TapData connectors repository. +- If the corresponding connector source is private, unavailable, or cannot be matched reliably, skip that check and mark it as `unverified`. +- Only flag clear conflicts, such as CDC support, write capability, incremental support, data types, authentication, network or permission prerequisites, or stated limitations that disagree with implementation. +- Lack of external corroboration by itself is not a defect. diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000..a7a2bd4 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,38 @@ +# AGENTS.md + +## Scope + +- This file supplements the default rules in the repository root `AGENTS.md`. +- It applies only to the current-version docs under `docs/**`. +- It does not override the special requirements for `versioned_docs/**`, `versioned_sidebars/**`, or root-level configuration files. + +## Writing Style + +- Use concise, professional, natural English technical writing. +- Avoid marketing tone, filler, and obvious AI phrasing. +- Explain what the user needs to do, why it matters, what the prerequisites are, and what caveats they should know. +- Keep established local terminology unless there is a strong reason to change it. + +## Current-Version Review Focus + +- Current product behavior, defaults, limits, and UI labels should reflect the current version. If uncertain, mark the point as `unverified` instead of guessing. +- Steps should clearly state prerequisites, sequence, and expected result. If an action is irreversible or involves permissions, network access, cost, or data risk, call that out explicitly. +- Keep internal links, heading anchors, relative paths, image references, doc IDs, and sidebar references consistent. In Docusaurus, doc IDs are derived from the source path unless front matter overrides them. +- Content under `docs/reuse-content/**` may be reused by multiple pages; when reviewing or editing it, consider downstream impact as well. +- References to files under `docs/images/**` must match the exact path, case, and extension. + +## Content Rules + +- Do not casually change code blocks, commands, parameter names, API field names, UI labels, version numbers, or documented limits. +- Keep heading hierarchy, list style, terminology, and link style aligned with nearby pages when possible. +- For capability, limitation, and compatibility statements, optimize for correctness over smoother wording. +- If a page claims a feature is `supported`, `enabled by default`, `requires no configuration`, or `has limitations`, ground that statement in page context, product facts, or implementation evidence whenever possible. If you cannot confirm it, say so. + +## Connector Documentation + +- Apply the following checks only when the change touches connector or prerequisite content under `docs/connectors/**` or `docs/cloud/prerequisites/**`. +- When feasible, lightly cross-check capability claims against connector implementation or metadata sources. +- One public reference source is the TapData connectors repository. +- If the corresponding connector source is private, unavailable, or cannot be matched reliably, skip that check and mark it as `unverified`. +- Only flag clear inconsistencies, such as CDC support, write capability, incremental support, data types, authentication flows, network or permission prerequisites, or stated limitations. +- Lack of external corroboration by itself is not a defect. diff --git a/docusaurus.config.js b/docusaurus.config.js index 924fc46..36518ac 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -28,6 +28,7 @@ const config = { docs: { routeBasePath: '/', // Serve the docs at the site's root sidebarPath: require.resolve('./sidebars.js'), + exclude: ['**/AGENTS.md', '**/AGENTS.override.md'], // Configuring versioning behavior and label /*lastVersion: 'current', versions: {