panurus

AI Agents Best Practices

Panurus project leverages AI agents to streamline development, maintenance, and testing. To ensure consistent and high-quality results when using AI agents, please follow the guidelines below.

Agent Context (AGENTS.md)

The AGENTS.md file in the root directory is the primary source of truth for AI agents. It provides a comprehensive overview of the project’s architecture, key components, building instructions, and development conventions.

When starting a session with an AI agent, ensure it has read this file to understand the project’s specific context.

Best Practices for AI-Assisted Development

1. Research and Strategy Before Execution

Before asking an agent to implement a feature or fix a bug, ensure it performs a research phase.

• Goal: Understand existing patterns and dependencies.
• Action: Use tools like grep_search, glob, and read_file to map the codebase.
• Verification: Always verify assumptions by reading the actual source code.

2. Empirical Bug Reproduction

Never apply a fix based on an observation alone.

• Goal: Confirm the failure state and prevent regressions.
• Action: Ask the agent to create a reproduction script or a new test case that fails before implementing the fix.

3. Idiomatic and Consistent Code

The agent must adhere to the project’s Go coding standards.

• Goal: Maintain a seamless and maintainable codebase.
• Action: Reference Writing idiomatic, effective, and clean Go code and ensure the agent uses make lint-auto-fix after making changes.

4. Comprehensive Testing and Validation

Validation is the only path to finality.

• Goal: Ensure correctness and prevent regressions.
• Action: Every change must include a testing strategy. For new features, this means adding unit tests or integration tests. For bug fixes, it means verifying the fix with the reproduction case.
• Mandate: Always run make unit-tests and relevant integration tests (e.g., make integration-tests-fabtoken-fabric-t1).

5. Surgical and Atomic Changes

Keep changes focused and minimal.

• Goal: Reduce complexity and make reviews easier.
• Action: Instruct the agent to perform surgical updates rather than broad refactorings, unless specifically requested.

Common Agent Workflows

• Bug Fixing: Research -> Reproduce -> Strategy -> Fix -> Validate.
• Feature Addition: Research -> Design -> Strategy -> Implement -> Test -> Validate.
• Documentation: Research -> Draft -> Review -> Refine.

Runbooks

Some recurring maintenance chores are captured as standalone, agent-agnostic runbooks under docs/development/, so any agent that has read AGENTS.md can execute them without re-deriving the steps each time:

• Update fabric-smart-client to latest main — bumps the FSC dependency across all Go modules, resolves resulting API/lint breakage until make checks is clean, then pauses for user confirmation before pushing or opening a PR. Also available in Claude Code as /update-fsc.
• Debugging Integration Tests — log locations, Docker/network inspection, and Ginkgo focus/skip techniques for diagnosing failing integration tests. Also available in Claude Code as /debug-integration-tests.

Issue & PR Submission

Non-trivial fixes/features should have a GitHub Issue before implementation (describing the problem, not the fix), and the resulting PR must link back to it and carry the same metadata (assignee, labels, milestone, Panurus project). See General Guidelines for the exact gh commands, including the GraphQL workaround needed to set an issue’s Type field. Always confirm with the user before pushing a branch or opening the actual PR/issue on GitHub.

Feedback and Iteration

If an agent provides suboptimal results, provide specific feedback based on the project’s conventions. Update AGENTS.md if there are persistent misunderstandings about the project’s architecture or standards.

This site is open source. Improve this page.