From 463691d19189a5a637da9562fbf9c9107f7bb01a Mon Sep 17 00:00:00 2001 From: GitInno <86991526+gitnnolabs@users.noreply.github.com> Date: Fri, 15 May 2026 06:47:48 -0300 Subject: [PATCH] Add Cursor rules for project context, PR workflow and code style Introduce .cursor/rules/*.mdc so the agent applies SciELO RCT objectives, mandatory docs/pr insumos, deliverables in Markdown, no-comments policy,extract-on-reuse, and Black/isort for Python. --- .cursor/rules/deliverables-markdown-files.mdc | 30 ++++++++++ .cursor/rules/extract-function-on-reuse.mdc | 24 ++++++++ .cursor/rules/no-comments.mdc | 12 ++++ .cursor/rules/pr-commit.mdc | 57 +++++++++++++++++++ .cursor/rules/project-objectives.mdc | 48 ++++++++++++++++ .cursor/rules/python-black-isort.mdc | 25 ++++++++ 6 files changed, 196 insertions(+) create mode 100644 .cursor/rules/deliverables-markdown-files.mdc create mode 100644 .cursor/rules/extract-function-on-reuse.mdc create mode 100644 .cursor/rules/no-comments.mdc create mode 100644 .cursor/rules/pr-commit.mdc create mode 100644 .cursor/rules/project-objectives.mdc create mode 100644 .cursor/rules/python-black-isort.mdc diff --git a/.cursor/rules/deliverables-markdown-files.mdc b/.cursor/rules/deliverables-markdown-files.mdc new file mode 100644 index 0000000..4e3ed54 --- /dev/null +++ b/.cursor/rules/deliverables-markdown-files.mdc @@ -0,0 +1,30 @@ +--- +description: Planos, tarefas, Github e descrições de PR como ficheiros MD organizados +alwaysApply: true +--- + +# Entregáveis em Markdown (ficheiros no repositório) + +Quando o pedido for **plano**, **descrição de tarefa**, **história ou issue para Jira**, ou **texto de pull request**, **não** limite a resposta ao chat: **crie ficheiros `.md` no projeto**, bem estruturados e reutilizáveis. + +## Onde guardar + +Use a pasta **`docs/plan`**, com subpastas por tipo (crie-as se não existirem): + +| Tipo | Pasta sugerida | Exemplo de nome | +|------|------------------|-----------------| +| Plano / roadmap de execução | `docs/plans/` | `YYYY-MM-DD-nome-curto-do-plano.md` | +| Tarefa / descrição de trabalho | `docs/tasks/` | `YYYY-MM-DD-nome-da-tarefa.md` | +| Pull request | `docs/pr/` | `pr-nome-do-ramo-ou-tema.md` ou `YYYY-MM-DD-pr-tema.md` | + +Se já existir convenção no repositório (prefixos `atividade-`, `docs/github-*`, etc.), **alinhe com ela** em vez de duplicar padrões conflituosos. + +## Conteúdo + +- **Cabeçalho**: título H1, data (ISO), contexto ou link de ticket quando houver. +- **Secções claras**: objetivo, âmbito, passos / critérios de aceite, riscos, follow-up — conforme o tipo de documento. +- **Linguagem**: a mesma do pedido do utilizador (ex.: português), salvo indicação contrária. + +## Resposta no chat + +Depois de criar ou atualizar os ficheiros, resuma no chat **o caminho dos ficheiros** e o essencial (uma ou duas frases), para o utilizador saber onde editar ou copiar para o GitHub. diff --git a/.cursor/rules/extract-function-on-reuse.mdc b/.cursor/rules/extract-function-on-reuse.mdc new file mode 100644 index 0000000..b01d48c --- /dev/null +++ b/.cursor/rules/extract-function-on-reuse.mdc @@ -0,0 +1,24 @@ +--- +description: Extrair função só quando houver reuso em pelo menos dois trechos +alwaysApply: true +--- + +# Funções apenas com reuso + +- **Não** crie funções (nem métodos privados auxiliares) só para “organizar” um único fluxo ou dar nome a um bloco usado **uma vez**. +- **Crie** uma função quando a mesma lógica for necessária em **dois ou mais** trechos de código (reuso real). + +## O que fazer em vez disso + +- Deixe o fluxo linear no escopo onde é usado uma vez. +- Use variáveis com nomes claros e blocos curtos em vez de micro-funções de uso único. + +## Exceções raras + +- **Framework / contrato**: funções ou métodos que o Django, Celery, etc. exigem como ponto de entrada (view, `action`, task, signal handler) — mesmo com um único registo, a função é o mecanismo obrigatório. +- **Testes**: fixtures/helpers partilhados por vários testes, conforme o ficheiro. +- **Código gerado** ou boilerplate obrigatório do projeto. + +## Parâmetros + +- Não adicionar * nas função a não ser que seja solicitado. \ No newline at end of file diff --git a/.cursor/rules/no-comments.mdc b/.cursor/rules/no-comments.mdc new file mode 100644 index 0000000..d8564d6 --- /dev/null +++ b/.cursor/rules/no-comments.mdc @@ -0,0 +1,12 @@ +--- +description: Código sem comentários — nomes e estrutura devem bastar +alwaysApply: true +--- + +# Sem comentários no código + +- Não adicione comentários de linha (`#`, `//`, `/* */`, ``, etc.) nem docstrings em código novo ou alterado. +- Não use comentários para “desligar” linhas ou marcar TODO/FIXME no código; use issues ou tarefas. +- Prefira nomes claros, funções pequenas e extração de métodos em vez de explicar com comentário. + +**Exceções (se o projeto já exigir):** cabeçalhos de licença em arquivos novos, ou comentários gerados por ferramentas que não devem ser editados manualmente. diff --git a/.cursor/rules/pr-commit.mdc b/.cursor/rules/pr-commit.mdc new file mode 100644 index 0000000..91be602 --- /dev/null +++ b/.cursor/rules/pr-commit.mdc @@ -0,0 +1,57 @@ +--- +description: Insumo obrigatório em docs/pr e mensagem de commit por tarefa com código +alwaysApply: true +--- + +# Insumo de PR e mensagem de commit (obrigatório) + +Em **todo pedido que produza ou altere código** no repositório (implementação, correção, refactor, testes novos), ao **concluir** o trabalho é **obrigatório** criar ou atualizar um ficheiro Markdown de insumo em `docs/pr/`. Não basta descrever só no chat. + +Pedidos **apenas informativos** (explicação, revisão sem alterações, perguntas) **não** exigem este ficheiro. + +## Onde guardar + +- Pasta: **`docs/pr/`** (criar se não existir). +- Nome: **`YYYY-MM-DD-.md`** ou **`pr-.md`**. +- Um ficheiro por tarefa/sessão de trabalho; se o mesmo ficheiro for reutilizado no mesmo dia/tema, **atualizar** o existente em vez de duplicar. + +## Estrutura obrigatória do ficheiro + +O insumo deve conter **duas partes**, nesta ordem: + +### 1. Mensagem de commit + +Secção **`## Mensagem de commit`** com texto **pronto a colar** no `git commit`: + +- Primeira linha: resumo imperativo, ≤72 caracteres, em português ou inglês conforme o padrão recente do repositório. +- Corpo opcional (linhas seguintes): o *porquê* da mudança, não só o *o quê*. +- Não incluir ficheiros secretos, `.env` ou artefactos locais no âmbito do commit. + +### 2. Corpo do PR (template do projeto) + +Reproduzir as secções do template oficial: + +`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` + +Preencher cada secção com conteúdo concreto da tarefa atual: + +| Secção no insumo | Conteúdo esperado | +|------------------|-------------------| +| **O que esse PR faz?** | Problema resolvido ou feature entregue. | +| **Onde a revisão poderia começar?** | Caminho(s) de ficheiro(s) para o revisor abrir primeiro. | +| **Como este poderia ser testado manualmente?** | Passos numerados reproduzíveis. | +| **Algum cenário de contexto que queira dar?** | Contexto editorial/técnico, decisões, limitações. | +| **Screenshots** | Quando aplicável; senão indicar *N/A*. | +| **Quais são tickets relevantes?** | Issue/Jira ou *N/A*. | +| **Referências** | RCT, ADR, links externos usados. | + +## Comportamento do agente + +1. Criar ou atualizar o ficheiro em `docs/pr/` **antes** de encerrar a tarefa (junto com o código, não depois). +2. No chat, indicar o **caminho do ficheiro** e repetir apenas a **mensagem de commit** (uma ou duas frases). +3. Ao abrir o PR no GitHub, copiar do insumo as secções do template para a descrição do PR; a mensagem de commit vem da secção **Mensagem de commit**. +4. Só fazer `git commit` quando o utilizador pedir explicitamente; mesmo sem commit, o insumo em `docs/pr/` é obrigatório. + +## Alinhamento + +Complementa a regra `deliverables-markdown-files.mdc` (planos, tarefas, PR). Para PRs, este ficheiro de insumo é o entregável **obrigatório** por tarefa com código. diff --git a/.cursor/rules/project-objectives.mdc b/.cursor/rules/project-objectives.mdc new file mode 100644 index 0000000..cd7f64e --- /dev/null +++ b/.cursor/rules/project-objectives.mdc @@ -0,0 +1,48 @@ +--- +description: Objetivos, escopo e princípios do SciELO RCT (MarkAPI) +alwaysApply: true +--- + +# SciELO Research Communication Tools (SciELO RCT) + +Plataforma para produção, avaliação e rastreio de objetos de comunicação de pesquisas (manuscritos, preprints, artigos, dados de pesquisa, livros, capítulos). Repositório: `scieloorg/markapi`. O XML SPS é o registro único e rastreável de cada objeto e de cada evento do ciclo editorial. + +## Objetivo geral + +Cobrir o ciclo completo — da submissão à disseminação — com marcação assistida por IA, avaliação informada, validação, geração de múltiplos formatos e rastreio de eventos no XML, integrando-se de forma agnóstica a sistemas editoriais via API REST (sem obrigar periódicos a trocar OJS, ScholarOne, etc.). + +## Objetivos específicos + +- Suportar os seis tipos de objeto: manuscrito, preprint, artigo, dado de pesquisa, livro, capítulo. +- Pipeline DOCX/LaTeX (e ODT como alternativa) → XML SPS com marcação assistida por LLM; revisão humana sempre possível antes de finalizar. +- Avaliação informada: checklists (CONSORT, PRISMA, STROBE, ARRIVE) e critérios FAIR; resultados registrados no XML com avaliador e timestamp. +- Rastreio no XML: submissão, parecer, decisão, marcação, validação, publicação — cada evento com timestamp, agente e metadados. +- Formatos de saída a partir do XML SPS: pacote `.zip` SPS, PDF por idioma, HTML, XML Crossref/PubMed/PMC/Web of Science, JSON DOAJ; correções no XML propagam aos derivados. +- API REST (JWT) para sistemas externos postarem eventos e operarem documentos; Wagtail embutido para quem não tem sistema editorial. +- Bases de referência (ORCID, ROR, Fundref, ISSN, licenças, DeCS/MeSH, etc.) para autocomplete, normalização e validação. +- Integrações SciELO: metadados via scielo.org; publicação via Upload/scms-upload → OPAC 5, com eventos de publicação de volta ao XML. +- Implantação: desktop, intranet ou internet (Docker Compose / Kubernetes). + +## Dentro do escopo + +Conversão e marcação; validação e PDF/HTML via packtools; LLM local (llama-cpp) ou remoto (configurável); registro de eventos e avaliação no XML; interface Wagtail; fluxo de revisão por pares nativo opcional; distribuição Docker/K8s. + +## Fora do escopo + +Substituir à força sistemas de revisão por pares já adotados; custear APIs de LLM de terceiros; desenvolver modelo de IA próprio; gestão de assinaturas ou acesso ao conteúdo publicado. + +## Princípios de implementação + +- IA auxilia marcação (destaque: referências bibliográficas); humano revisa e corrige; persistir resultados para auditoria e reuso. +- Integração aditiva: periódicos mantêm seus fluxos; a plataforma é backbone editorial via API. +- Conformidade SPS: validar com packtools (versão fixada no projeto). +- Privacidade: preferir LLM on-premise; API externa é responsabilidade da instituição. +- Stack principal: Python 3, Django 5, Wagtail 6, DRF, Celery + Redis, PostgreSQL, lxml/python-docx + packtools, apps `xml_manager`, `reference`, `model_ai`, `docx_layouts`, `tracker`. + +## Critérios de sucesso (referência) + +Redução ≥50% no tempo de marcação; ≥90% validação packtools sem erros; ≥85% precisão LLM em referências (amostragem); PDF sem defeitos críticos em revisão amostral; satisfação ≥4/5. + +## Especificação completa + +Documento de referência: `scielo_rct_v3_updated.docx` (SciELO RCT v4.0). Para detalhes de arquitetura, perfis, cronograma e glossário, consultar o RCT ou pedir `@` do ficheiro em `docs/spec/` quando existir cópia versionada no repositório. diff --git a/.cursor/rules/python-black-isort.mdc b/.cursor/rules/python-black-isort.mdc new file mode 100644 index 0000000..010134e --- /dev/null +++ b/.cursor/rules/python-black-isort.mdc @@ -0,0 +1,25 @@ +--- +description: Python formatado com Black e imports com isort (pyproject.toml) +globs: "**/*.py" +alwaysApply: false +--- + +# Black + isort em todo código Python + +O projeto define `[tool.black]` e `[tool.isort]` com `profile = "black"` e `line-length = 88` em `pyproject.toml`. Siga isso ao escrever ou alterar `.py`. + +## Ao terminar edições em arquivos Python + +Rode os dois a partir da raiz do repositório, **nesta ordem** (imports primeiro, formatação depois): + +1. `isort ` +2. `black ` + +Isso evita que o Black refaça linhas e o isort precise rodar de novo. + +Se o ambiente não tiver os binários no PATH, use os do projeto (`make`/pipx conforme `Makefile`) ou `python -m black` / `python -m isort`. + +## Estilo + +- Linha máxima **88** caracteres (Black). +- Imports agrupados de acordo com isort **profile black**, sem conflitar com o Black.