[Cedric Vidal (cedricvidal)]

Summary

AI coding agents can produce code that is functionally correct but difficult for people to read. This is visible with GPT models, but it is a broader model- and agent-independent problem: generated code may favor dense control flow, few visual separators, limited comments, and types or parameters whose meaning is left implicit. That slows reviews and makes changes harder to maintain safely.

This PR provides one concise, repository-wide styling guide for every coding agent. It asks agents to:

• prefer clear names, small functions, simple control flow, and visible separation between logical steps;
• explain every non-trivial function and logical block without narrating obvious code;
• document parameter and type semantics, constraints, units, optionality, and defaults where relevant;
• keep guidance centralized in AGENTS.md, with CLAUDE.md loading the same instructions for Claude-based agents.

The result is a homogeneous readability standard regardless of which coding model or agent authors the change.

Demos

N/A — repository instruction documentation only; no user-visible Portal/CLI change.

Before

N/A.

After

N/A.

Testing

• git diff --check — passed.
• Changed-file check — passed; the change contains exactly AGENTS.md and CLAUDE.md.
• Loader check — passed; CLAUDE.md imports the existing AGENTS.md and contains only the loader-only reminder.
• Extraction check — passed; removing the new readability section restores the original AGENTS.md byte-for-byte.

Runtime tests and model calls were not run because this is documentation-only and does not alter production behavior or a static prompt family.

Documentation and compatibility

AGENTS.md contains the shared readability expectations. Root CLAUDE.md loads that file so all agent guidance remains centralized. No breaking changes, API/CLI compatibility impact, or upgrade steps.

Checklist

• If Portal features changed, keep CLI capabilities in sync. N/A — no Portal features changed.
• If Portal components changed, update their Storybook stories. N/A — no components changed.
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. N/A — no database changes.
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. N/A — no dependency changes.
• Video showing the behavior before the suggested change — N/A, instruction documentation only.
• Video showing the behavior after the suggested change — N/A, instruction documentation only.