René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Add AGENTS.md to this repository for coding agent onboarding","articleBody":"## Issue Description\n\nThis repository is missing an `AGENTS.md` file at the root. That file is used to **onboard a coding agent (like GitHub Copilot's automation agents)** so it can work efficiently and correctly in this codebase.\n\nProviding high-quality, explicit repository instructions dramatically reduces:\n- Broken or failing CI / build attempts\n- Wasted exploration (grep/find excessive searches)\n- Incorrect environment setup\n- PR churn due to missing context\n\n## Required Action\n\nCreate a new `AGENTS.md` file in the repository root with the following high‑level sections (in this order):\n\n1. **Overview** – What the project does, main technologies, primary entry points.\n2. **Code layout** – Bullet list of important files / folders with brief purpose (Python modules, infra/Bicep, workflows, scripts, config). Omit trivial or generated files.\n3. **Running the code** – Step‑by‑step environment setup (preferred Python version / tool, how to install deps, how to run main scripts). Prefer using GitHub Models if applicable over Azure-only model configs.\n4. **Running the tests** – Exact commands to run the test suite (include any required env vars, virtualenv activation, or formatting/lint steps if enforced by CI).\n5. **Upgrading Python dependencies** – How to add or upgrade a dependency (e.g., edit `requirements.txt` and run a pin/update command). Include any tools (pip, uv, etc.).\n6. **Release / build / deployment notes** (if applicable) – Any scripts, workflows, or manual steps the agent must respect.\n7. **Conventions \u0026 gotchas** – Linting rules, code style, required env vars, secrets handling, common pitfalls.\n8. **Validation checklist** – A short ordered list the agent should follow before opening a PR (e.g., tests pass locally, formatting applied, no stray debug prints, etc.).\n9. **When to search** – A closing note instructing the agent to trust `AGENTS.md` and only perform source-wide searches if information is missing or incorrect.\n\n## Authoring Guidelines (Summarized from canonical AGENTS.md guidance)\n\n- Be explicit: Prefer concrete commands over prose (e.g., `pytest -q` not “run tests”).\n- Verify every command before including it.\n- List required environment variables and how they’re obtained.\n- Document any non-obvious build or test ordering.\n- Surface known flaky areas, hacks, or TODO hotspots if they affect modification strategy.\n- Keep it concise but information-dense—optimize for an automated agent, not a marketing audience.\n\n## Example Skeleton\n\n```markdown\n# AGENTS.md\n\n## Overview\n\u003c1–3 paragraph summary\u003e\n\n## Code layout\n- `agent.py` – Entry point for ...\n- `checks/` – YAML definitions for automated repo code checks\n- `infra/` – Bicep templates for infra provisioning\n- `.github/workflows/` – CI/CD workflows\n...\n\n## Running the code\n1. Create virtual environment: `python -m venv .venv \u0026\u0026 source .venv/bin/activate`\n2. Install deps: `pip install -r requirements.txt`\n3. Run main script: `python agent.py --help`\n\n## Running the tests\n```bash\nsource .venv/bin/activate\npytest -q\n```\n\n## Upgrading Python dependencies\nEdit `requirements.txt`, then: `pip install -r requirements.txt` and run tests.\n\n## Validation checklist\n- [ ] Virtualenv active\n- [ ] `pytest -q` passes\n- [ ] No debug prints\n- [ ] Updated docs if behavior changed\n\n## When to search\nOnly search the codebase if required info is missing or appears outdated.\n\n## Acceptance Criteria\n\n- `AGENTS.md` exists at repository root\n- Contains all required sections above\n- Commands verified and minimal\n- Provides actionable, agent-focused guidance\n\nAdding this file will significantly improve automated contribution quality.\n\n\n\n\n---\n*This issue was automatically created by the GitHub Repo Maintainer Agent.*","author":{"url":"https://github.com/pamelafox","@type":"Person","name":"pamelafox"},"datePublished":"2025-09-30T17:53:57.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/273/rag-postgres-openai-python/issues/273"}