sanjeed5/awesome-cursor-rules-mdc

1. What this repository is

- This is a Python-based content generation pipeline, not an application runtime.

- Its job is to turn a structured library catalog in rules.json into many Cursor MDC rule files under rules-mdc/.

2. Core data model boundary

- The primary input is rules.json, which lists libraries and tags.

- The generator treats that file as the source of truth for what should be produced, while existing generated files in rules-mdc/ represent the output artifact set.

3. Main orchestration script

- src/generate_mdc_files.py is the central entry point and likely coordinates the whole workflow.

- The README shows it supports selective processing (--library, --tag), test runs, regeneration, verbosity, worker count, and rate limiting.

4. Configuration and runtime settings

- src/config.yaml holds operational settings such as rate limits, output directories, model selection, and processing parameters.

- Environment variables from .env supply API credentials, so secret management is separated from code and config.

5. External service dependencies

- Exa is used for semantic search to collect best-practice material and supporting context.

- A large-language-model provider, typically Gemini but optionally OpenAI or Anthropic, generates the final rule content.

- These are the only materially important external integrations in the repo’s architecture.

6. Generation pipeline

- The workflow is: read the library definition → gather supporting information via Exa → feed that context plus instructions into the LLM → write an MDC file.

- src/mdc-instructions.txt appears to define the generation prompt or content constraints that shape the output format.

7. Parallelism and throughput control

- The generator is designed to process multiple libraries concurrently via worker settings.

- API usage is controlled by a rate-limit mechanism, which matters because the pipeline depends on two external APIs and is sensitive to quota and throttling.

8. Resume and failure handling

- src/mdc_generation_progress.json tracks progress across runs so interrupted jobs can resume.

- The default mode only retries libraries that previously failed, which makes the process incremental rather than fully stateless.

9. Intermediate artifacts

- src/exa-example.py suggests there is an example or helper path for Exa integration, likely separate from the main batch workflow.

- src/logs/ and the progress JSON provide observability and recovery rather than persisting application state in a database.

10. Output layer

- Generated MDC files are emitted into rules-mdc/, with one file per library or rule topic.

- That directory is effectively the product of the pipeline and the handoff point for downstream Cursor usage.

11. Legacy and migration area

- rules-v0-deprecated/ contains older prompt files, conversion scripts, and a conversion report.

- Architecturally, this looks like an archive of prior-generation formats and migration tooling, distinct from the active generator path.

12. Project tooling

- The project is Python-managed with uv (pyproject.toml, uv.lock, .python-version).

- The repository also includes .env.example and a MIT license, indicating a lightweight CLI/tooling project rather than a deployed service.

13. How to draw the architecture

- The diagram should center on a CLI batch processor in src/generate_mdc_files.py.

- Show inputs from rules.json, config.yaml, and .env; external calls to Exa and an LLM API; internal progress/log tracking; and final writes to rules-mdc/.

- Treat rules-v0-deprecated/ as a secondary archival branch, not part of the active execution path.