Large Skill: System Design Field Guide

Large Skill: System Design Field Guide

This skill contains a longer narrative that resembles the kind of internal field guide teams use when designing new systems. It is not intended to be exhaustive, but it is intentionally verbose so that token-counting tests have a substantial body of text to work with.

1. Clarify the Problem

Every system design effort should begin with a careful restatement of the problem. Engineers should write down:

• Who the primary users are and what they are trying to achieve.
• The most important success metrics for the system.
• Explicit non-goals that are deliberately out of scope.
• Constraints related to latency, throughput, security, or compliance.

Capturing these items up front makes it easier to evaluate trade‑offs later. When the design diverges from the original problem statement, the team can either adjust expectations or update the requirements.

2. Identify Boundaries and Responsibilities

System diagrams are useful, but they must be backed by well-defined boundaries. Each component should have a crisp responsibility such as "serves read‑only product data" or "handles authenticated user sessions." When responsibilities are vague, coupling tends to increase and it becomes difficult to reason about failures.

Consider documenting:

• Which components own which data sets.
• Which APIs are stable contracts versus internal details.
• How requests flow through the system from entry point to storage.
• Where cross-cutting concerns such as logging and metrics live.

These notes rarely appear in user-facing documentation, but they are precisely the kind of content that internal skills can capture.

3. Data Modeling and Storage

Choosing the right data model is often more important than picking a particular database product. For each major entity, describe:

• The fields and their types.
• How entities relate to one another.
• Which access patterns must be fast and which can be slower.
• How historical data should be archived or deleted.

During testing, this section serves simply as additional text that increases the size of the large skill. The token counter does not need to understand the semantics; it only needs to see that this content is substantially larger than the metadata header used at progressive disclosure level one.

4. Performance and Scalability

Performance planning starts with realistic assumptions about traffic. Design documents should include back‑of‑the‑envelope calculations for:

• Requests per second in steady state.
• Expected spikes during peak events or batch jobs.
• Storage growth over one, two, and three years.
• The cost of serving an average request.

Engineers can use these estimates to decide whether to introduce queues, caching layers, background workers, or read replicas. When documenting these decisions in a skill, it is helpful to explain the reasoning in plain language so that future maintainers can understand why certain trade‑offs were made.

5. Resilience and Operations

No system is perfect, so designs must include a plan for failure. This section should answer questions such as:

• What happens when a dependency is slow or unavailable?
• How are partial failures reported to users?
• Which alerts are critical and which are informational?
• How do we perform controlled rollbacks when a deployment goes wrong?

Operational guidance may also cover runbooks, on‑call expectations, and playbooks for common incidents. Again, from the perspective of token efficiency tests, these paragraphs simply provide more natural language for the encoder to process.

6. Supplementary Reference Material

Longer design documents often refer to additional material such as sequence diagrams, API schemas, or architectural decision records. In this skill we model that pattern using a separate reference file:

See the extended notes in the reference document for more detailed examples, diagrams, and checklists.

The loader should treat this as a normal markdown link. Tests that exercise progressive disclosure at level three can assert that the content of the reference file is not automatically inlined when the skill is loaded; instead, only the path to the document is expanded to an absolute filesystem path.