harness-sdk AGENTS.md

Agent Development Guide - Strands Agents Monorepo

This document provides guidance for AI agents working in the Strands Agents monorepo. For human contributor guidelines, see CONTRIBUTING.md.

This file is shared by agents with different goals — writing code, opening PRs, helping contributors — and is organized by task.

Context

Monorepo Layout

strands-agents/
├── strands-py/         # Python SDK (hatch) — see strands-py/AGENTS.md
├── strands-ts/         # TypeScript SDK (npm workspace) — see strands-ts/AGENTS.md
├── site/               # Documentation site (Astro) — see site/AGENTS.md
├── team/               # Governance + cross-SDK process (tenets, decisions, API bar-raising, PR & compatibility guidelines, designs/ proposals)
├── test-infra/         # CDK stack for integ tests that require provisioned AWS infra
├── .agents/            # Agent skills and references
├── package.json        # npm workspace root
└── .github/workflows/  # CI (ci.yml is the merge gate)

Determine which sub-project you're in and follow its conventions — each has its own AGENTS.md.

Where the "why" lives: team/

Before designing a feature or changing an API, read the relevant context in team/. It captures the reasoning the code itself doesn't:

• team/designs/ — RFC-style proposals for significant features (numbered NNNN-*.md). The richest source of architectural context: problem framing, the chosen approach, alternatives considered, and consequences. If you're touching a major subsystem, find its design doc first.
• team/DECISIONS.md — lightweight architecture decision records for smaller calls.
• team/TENETS.md — the principles a contribution should align with.
• team/API_BAR_RAISING.md and team/FEATURE_LIFECYCLE.md — the bar and process for API changes and feature deprecation.

Writing Code

• Code conventions: Follow the conventions in the sub-project's own AGENTS.md (strands-py/AGENTS.md, strands-ts/AGENTS.md, site/AGENTS.md) — they define the style, patterns, and directory layout for that toolchain.
• Write for low complexity: every PR is labeled with the cognitive complexity of the most complex function it touches, and nesting drives the score. Write flat control flow (guard clauses, extracted helpers, lookup tables over branch ladders) and keep refactors in their own PR. Why we measure and how the score works: team/COMPLEXITY.md. Check before pushing with npm run complexity (or hatch run complexity from strands-py/).
• Branching: git checkout -b agent-tasks/{ISSUE_NUMBER}
• Commits: Use conventional commits — feat:, fix:, refactor:, docs:, etc.
• CI: The ci.yml merge gate detects which paths changed and runs only relevant checks.
• Skills: Reusable, repo-specific workflows live under .agents/skills/ — for PRs (pr-create, pr-writer, pr-feedback), docs (docs-writer, docs-reviewer, docs-audit, docs-planner), and code review (strands-review). See .agents/skills/README.md for what each does and when to use it.
• Doc sourceLinks track source files: Doc pages under site/ point at their backing implementation via sourceLinks frontmatter — repo-relative paths into strands-py/ and strands-ts/. When you rename or move a source file, update any sourceLinks that reference its old path in the same change. The site build only fails on a malformed path or an unmapped file extension, not on a path that still resolves to the wrong (or now-nonexistent) file, so a stale reference rots silently. Find affected pages with grep -rn "<old/path>" site/src/content/docs.