[PR #94] [MERGED] Refactor Agents.md with progressive disclosure #278

New issue

Closed

opened 2026-02-26 21:34:24 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 21:34:24 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/rudrankriyam/App-Store-Connect-CLI/pull/94
Author: @rudrankriyam
Created: 1/24/2026
Status: ✅ Merged
Merged: 1/24/2026
Merged by: @rudrankriyam

Base: main ← Head: refactor/agents-md-progressive-disclosure

📝 Commits (2)

3780142 Refactor Agents.md with progressive disclosure
1c689da Address review feedback for Agents.md refactor

📊 Changes

5 files changed (+226 additions, -353 deletions)

View changed files

📝 Agents.md (+31 -353)
➕ docs/API_NOTES.md (+40 -0)
➕ docs/CONTRIBUTING.md (+44 -0)
➕ docs/GO_STANDARDS.md (+47 -0)
➕ docs/TESTING.md (+64 -0)

📄 Description

Summary

Reduce root Agents.md from ~360 lines to ~50 lines (~87% reduction)
Extract detailed documentation to docs/ directory for progressive disclosure
Emphasize using --help to discover commands instead of documenting every command

Changes

Root file (Agents.md):

Core principles (explicit flags, JSON-first, no prompts, pagination)
Discovering commands via --help
Build & test commands
Environment variables
Links to detailed docs

New docs:

docs/GO_STANDARDS.md - Go coding conventions
docs/TESTING.md - Testing patterns and guidelines
docs/CONTRIBUTING.md - Git workflow, adding commands/endpoints
docs/API_NOTES.md - Analytics, finance, sandbox quirks

Rationale

Based on progressive disclosure principles:

Agents should discover commands via --help, not memorize documentation
Root file stays minimal to reduce token usage
Detailed docs available when needed for specific tasks

Test plan

Verify --help output is sufficient for command discovery
Confirm docs links work and content is accessible
Test that AI agents can work with minimal root file

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/rudrankriyam/App-Store-Connect-CLI/pull/94 **Author:** [@rudrankriyam](https://github.com/rudrankriyam) **Created:** 1/24/2026 **Status:** ✅ Merged **Merged:** 1/24/2026 **Merged by:** [@rudrankriyam](https://github.com/rudrankriyam) **Base:** `main` ← **Head:** `refactor/agents-md-progressive-disclosure` --- ### 📝 Commits (2) - [`3780142`](https://github.com/rudrankriyam/App-Store-Connect-CLI/commit/37801424794c4b326a3779d1e9641cc2aae5346c) Refactor Agents.md with progressive disclosure - [`1c689da`](https://github.com/rudrankriyam/App-Store-Connect-CLI/commit/1c689da91534388e0c913aad8d70c716ae9f7f51) Address review feedback for Agents.md refactor ### 📊 Changes **5 files changed** (+226 additions, -353 deletions) <details> <summary>View changed files</summary> 📝 `Agents.md` (+31 -353) ➕ `docs/API_NOTES.md` (+40 -0) ➕ `docs/CONTRIBUTING.md` (+44 -0) ➕ `docs/GO_STANDARDS.md` (+47 -0) ➕ `docs/TESTING.md` (+64 -0) </details> ### 📄 Description ## Summary - Reduce root Agents.md from ~360 lines to ~50 lines (~87% reduction) - Extract detailed documentation to `docs/` directory for progressive disclosure - Emphasize using `--help` to discover commands instead of documenting every command ## Changes **Root file (`Agents.md`):** - Core principles (explicit flags, JSON-first, no prompts, pagination) - Discovering commands via `--help` - Build & test commands - Environment variables - Links to detailed docs **New docs:** - `docs/GO_STANDARDS.md` - Go coding conventions - `docs/TESTING.md` - Testing patterns and guidelines - `docs/CONTRIBUTING.md` - Git workflow, adding commands/endpoints - `docs/API_NOTES.md` - Analytics, finance, sandbox quirks ## Rationale Based on progressive disclosure principles: 1. Agents should discover commands via `--help`, not memorize documentation 2. Root file stays minimal to reduce token usage 3. Detailed docs available when needed for specific tasks ## Test plan - [ ] Verify `--help` output is sufficient for command discovery - [ ] Confirm docs links work and content is accessible - [ ] Test that AI agents can work with minimal root file --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>