Skip to content

Add testing and type annotation conventions to AGENTS.md #8

Open

Description

@fullsend-ai-retro

What happened

The code agent created PR #7 implementing personalized greetings (issue #4). The first review found two low-severity findings that the code agent could have avoided:

  1. Test naming inconsistency (tests/test_main.py): tests for get_greeting_name() used the pattern test_<function>_<behavior> while tests for main() omitted the function name prefix. The review requested consistent naming.
  2. Missing return type annotation (src/fullsend_python/main.py): get_greeting_name() had -> str but main() lacked -> None, creating inconsistent annotation coverage.

Both findings were addressed by the fix agent (cost $0.76) and verified by the re-review (cost $2.92). The repo's AGENTS.md currently documents project structure and build commands but contains no coding conventions that would guide the code agent on test naming or type annotations.

What could go better

The code agent has no repo-specific conventions to follow for test naming patterns or type annotation requirements. Without explicit guidance in AGENTS.md, the agent made reasonable but inconsistent choices — using two different test naming patterns in the same file and annotating one function but not another.

These are minor findings individually, but they contributed to the review-fix-re-review cycle that cost $3.68. If AGENTS.md documented the expected conventions, the code agent would likely follow them on the first attempt, avoiding the rework.

Confidence: moderate. The code agent generally follows AGENTS.md guidance well (it correctly used uv, placed code under src/fullsend_python/, etc.). Adding conventions there is the natural mechanism for this repo. However, this is a young repo with only 2 closed issues, so conventions may evolve — overly prescriptive guidance now could become stale quickly.

Proposed change

Add a Conventions subsection to AGENTS.md covering testing and type annotations. Specifically:

## Conventions

- Use `uv` for all dependency and lifecycle management.
- Source code lives under `src/fullsend_python/`.
- Keep the application entry point in `src/fullsend_python/main.py`.
- Document requirements in the `docs/` folder.
- All functions must have return type annotations (use `-> None` for functions that return nothing).
- Test functions follow the pattern `test_<function_name>_<behavior>` (e.g., `test_get_greeting_name_returns_username`).
- Run tests with `uv run pytest tests/ -v`.

This adds three new bullet points to the existing Conventions section: return type annotations, test naming pattern, and the test run command. The test command is also useful context for the code agent when adding tests.

Validation criteria

On the next code agent run that creates or modifies Python functions and tests in this repo, verify:

  1. All new functions include return type annotations (including -> None).
  2. All new test functions follow the test_<function_name>_<behavior> naming pattern.
  3. The review agent does not flag naming-convention or api-shape findings for the same issues.

Sample size: the next 3 code agent PRs that touch Python source and test files.


Generated by retro agent from #7

Activity

  1. fullsend-ai-triage commented on Sep 9, 2026

    @fullsend-ai-triage

    🤖 Finished Triage · ✅ Success · Started 9:09 PM UTC · Completed 9:13 PM UTC

    Commit: e9bff5b · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.64

  2. fullsend-ai-triage commented on Sep 9, 2026

    @fullsend-ai-triage

    This is a well-scoped documentation change with an exact proposed diff provided in the issue body. Note that PR #6 (for issue #5) also modifies the Conventions section of AGENTS.md to add the uv.lock convention — the two changes are independent but touch the same section, so a minor merge may be needed depending on landing order.

    Proposed test case:

    1. Verify AGENTS.md Conventions section contains all three new bullets:
       - Return type annotation requirement (including -> None)
       - Test naming pattern: test_<function_name>_<behavior>
       - Test run command: uv run pytest tests/ -v
    2. Verify the existing four convention bullets are preserved.
    3. On the next 3 code agent PRs touching Python source and tests,
       confirm no review findings for naming-convention or type-annotation
       inconsistencies.
    

    Next steps:

    • /fs-code — agent creates a PR to implement this issue
    • /fs-code <your instruction> — agent implements with your specific guidance
  3. fullsend-ai-coder commented on Sep 9, 2026

    @fullsend-ai-coder
    Contributor

    🤖 Finished Code · ✅ Success · Started 9:14 PM UTC · Completed 9:18 PM UTC

    Commit: e9bff5b · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.82

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationready-for-triageTriggers triage agent dispatchready-to-codeTriggers code agent dispatch

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions