asc-cli
CLAUDE.md393 starsChanged 37 days agoApache-2.0View on GitHub
It holds only what applies to every task; everything else is linked. You MUST write a failing test before writing any production code. This rule overrides every other instinct, including "the change is small", "it's just a one-liner", "I'll add the test after". If you catch yourself opening a file under Sources/ before a test under Tests/ exists and fails, stop and reverse course. Pre-implementation gate — before editing anything in Sources/, you must have done all of the following…
- Reads credentials
In this repository4 other files it gives its agents.
- app-implement-featureSkill
- fix-bugSkill
- implement-featureSkill
- improvementSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Run swift test (or a --filter'd subset) and observed the test fail — compile error counts as a failing test only if the assertion is the …
- Very specific: line 16
Only after step 4 may you write code under Sources/.
- Very specific: line 57
Every model carries its parent ID (AppStoreVersion.appId, AppScreenshot.setId).
- Very specific: line 59
CAEOAS: every model provides structuredAffordances — ready-to-run next commands, state-aware (e.g.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. It holds only what applies to every task; everything else is linked.
TDD is non-negotiable (read this first)
You MUST write a failing test before writing any production code. This rule overrides every other instinct, including "the change is small", "it's just a one-liner", "I'll add the test after". If you catch yourself opening a file under Sources/ before a test under Tests/ exists and fails, stop and reverse course.
Pre-implementation gate — before editing anything in Sources/, you must have done all of the following in order:
- Stated the user-facing behaviour in one sentence (e.g. "a version is live when state is
READY_FOR_SALE"). - Written a test in
Tests/that asserts the exact expected output for that behaviour. - Run
swift test(or a--filter'd subset) and observed the test fail — compile error counts as a failing test only if the assertion is the reason it can't compile (e.g. missing symbol the test names). - Reported the red result back to the user (one line is fine: "test X fails with:
<message>").
Only after step 4 may you write code under Sources/.
If you skip the gate, you are violating the project's primary rule. Treat this the same as committing secrets or force-pushing main.
Testing rules
Chicago School — state-based, not interaction-based: tests verify what domain objects return and compute, not how they call collaborators. Red → green → refactor, every time.
- Name tests
should <outcome> [when <situation>], with backticks, in the words of whoever sees the result (person, agent, REST client):func `should be live when the version is ready for sale`(). Never a method, type or mechanism verb (returns,calls,passes,maps). Rename older tests when you touch them; don't sweep. → Naming tests - Assert exact output values (
"READY_FOR_SALE","expired": true), never "is non-empty" or "doesn't throw". Command tests assert the full JSON string. - Implement just enough to pass — no extra fields, no speculative branches.
- Difficult to test = design problem. Never modify a test to make it pass; if it fails unexpectedly, the spec was wrong.
@Testing(not XCTest);@Mockableprotocols withgiven().willReturn(); shared test data inTests/DomainTests/TestHelpers/MockRepositoryFactory.swift.
Commands
swift build # debug build (-c release for release)
swift test # all tests
swift test --filter 'AppTests' # tests matching a pattern
swift test --enable-code-coverage # with coverage
make run ARGS="apps list" # run the CLI
make docs # regenerate docs/commands.md + docs/README.md
make check-docs # broken links, doc size budgetsArchitecture
Three strict layers, dependencies pointing one way: ASCCommand → Infrastructure → Domain.
Sources/
├── Domain/ # Pure value types, @Mockable protocols — zero I/O
├── Infrastructure/ # Implements Domain protocols via appstoreconnect-swift-sdk
└── ASCCommand/ # CLI entry (ASC.swift), output formatting, REST server (Commands/Web/), TUIDomain folders mirror the App Store Connect resource hierarchy (Domain/Apps/Versions/Localizations/…); Infrastructure and Tests/ mirror Domain exactly. Look at the tree rather than a list here.
Rules every change follows:
- Domain models are
public struct+Sendable+Equatable+Codable; the JSON encoding is the public schema. Optional text fields useencodeIfPresentso nil is omitted. - Every model carries its parent ID (
AppStoreVersion.appId,AppScreenshot.setId). The API doesn't return parent IDs, so Infrastructure mappers inject them from the request. - State enums expose semantic booleans (
isLive,isEditable,isPending) for agent decisions. - CAEOAS: every model provides
structuredAffordances— ready-to-run next commands, state-aware (e.g.submitForReviewonly whenisEditable). The CLIaffordancesand REST_linksboth derive from it. - CLI and REST ship together: a command that returns data is also exposed by
asc web-server. A feature isn't done until it is reachable over REST. AppStoreVersionLocalization(asc version-localizations: whatsNew, description, keywords) andAppInfoLocalization(asc app-info-localizations: name, subtitle, privacy URLs) are different resources with different repositories. Don't mix them up.
Why it's built this way: docs/design.md.
When you are…
- adding a feature →
implement-featureskill (architecture approval, TDD phases, REST exposure checklist, docs) - improving an existing one →
improvementskill - fixing a bug →
fix-bugskill - touching docs → docs/documentation-design. In short: new feature =
docs/features/<x>/README.md+ one CHANGELOG line +make docs; fix = one CHANGELOG line. Never hand-editdocs/commands.mdordocs/README.md. - working with auth or credentials → docs/features/asc-auth (
~/.asc/credentials.jsonfirst, thenASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATHenv vars, viaCompositeAuthProvider) - working with iris (private API) → docs/features/iris
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

