Skip to content

docs(agents): add AGENTS.md, agent guides and Claude Code guardrails - #2

Merged
MendesMat merged 5 commits into
mainfrom
docs/ai-agent-guidelines
Sep 25, 2026
Merged

MendesMat merged 5 commits into
mainfrom
docs/ai-agent-guidelines

Conversation

@MendesMat

@MendesMat MendesMat commented Sep 25, 2026 •

Copy link
Copy Markdown
Owner

What

Adds the guidelines for the AI coding agents that commit to this repository, following the practices recommended by GitHub's study of 2,500+ AGENTS.md files, the Claude Code documentation and the agents.md specification.

  • AGENTS.md: entry point read by most agents (Codex, Copilot, Cursor, Gemini, Claude), 135 lines:
    • stack with versions and verified commands (including a filtered test run and the formatting check);
    • pair programmer role: explore → plan → implement → verify, evidence instead of claims, stop after two failed attempts, disagree respectfully, teach the why;
    • three-tier boundaries: Always / Ask first / Never;
    • security and privacy: LGPD personal and sensitive data, no personal data or tokens in logs, fictitious test data, external text treated as data, not instructions;
    • gotchas: Microsoft.Testing.Platform, the two meanings of "Gerenciador", PowerShell 5.1, IPv6 localhost, HTTPS certificate;
    • instruction precedence, definition of done and a self-maintenance rule.
  • CLAUDE.md: imports AGENTS.md, so Claude Code shares the same source of truth.
  • .claude/settings.json: Claude Code permission rules that block pushing to main, force pushing and trusting certificates, for both Bash and PowerShell.
  • docs/agents/guides/: architecture, domain glossary (pt-BR → code → wire), coding conventions, testing, documentation, local environment, communication.
  • docs/agents/workflows/: git and pull requests, implement a feature, record a decision, review dependency updates.
  • docs/agents/trabalhando-com-agentes.md (Portuguese): how the owner asks for tasks, reviews pull requests and pairs with agents.
  • Links from the root README and CONTRIBUTING; .gitignore excludes .claude/settings.local.json.

Why

Commits will be made by AI agents. The rules that protect the project must be explicit, short enough to be followed, and enforced where possible.

Decisions taken by the owner:

  • Agents open pull requests and stop; the owner reviews and merges.
  • Commits do not carry Co-authored-by lines.

How to test

  • Open AGENTS.md and follow the links: all 18 agent-related Markdown files were checked for broken relative links.
  • The deny rules were simulated against 15 commands: 9 dangerous ones blocked, 6 normal ones allowed (including dotnet dev-certs https --check --trust, which only reads). Claude Code also enforced them live during this session.
  • dotnet build, dotnet test and dotnet format --verify-no-changes pass (documentation and configuration only).

Checklist

  • Tests cover the new behavior (documentation and configuration only, no code change)
  • dotnet test --solution ControlService.slnx passes locally
  • Documentation updated
  • User-facing messages follow the tone in docs/03-regras-de-negocio.md (not applicable)

AGENTS.md is the entry point shared by most coding agents; CLAUDE.md
imports it. Detailed guides and step-by-step workflows live in docs/agents.
…ain glossary

Reorganizes AGENTS.md following GitHub's AGENTS.md study and the Claude Code
best practices: stack versions and verified commands first, pair programmer
role, Always / Ask first / Never boundaries, security and privacy (LGPD),
gotchas, precedence and a self-maintenance rule. The domain glossary gives
one translation for every business term.
Deny rules for Bash and PowerShell: push to main, force push and trusting the
HTTPS development certificate. Personal settings stay out of git.
@MendesMat MendesMat changed the title docs(agents): add AGENTS.md with guides and workflows for AI agents docs(agents): add AGENTS.md, agent guides and Claude Code guardrails Sep 25, 2026
@MendesMat
MendesMat merged commit bf25485 into main Sep 25, 2026
5 checks passed
@MendesMat
MendesMat deleted the docs/ai-agent-guidelines branch September 25, 2026 02:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant