the holy quest for the holy home

7.0 KiB

Raw Blame History

AGENTS.md — Busca de Imóveis DF

Finalidade

Este repositório apoia a coleta, organização e análise histórica de anúncios imobiliários do Distrito Federal para uma decisão residencial de longo prazo.

Antes de trabalhar no projeto, leia integralmente:

docs/PROJECT_CONTEXT.md
docs/PROPERTY_CRITERIA.md
docs/DATA_MODEL.md
docs/ANALYSIS_RULES.md

Esses documentos são a referência operacional do projeto. Quando houver conflito:

uma instrução explícita e recente do usuário prevalece;
depois, prevalecem estes documentos;
por último, hipóteses inferidas a partir dos dados.

Nunca trate uma hipótese como preferência confirmada.

Para auxiliar no entendimento e contexto, as plantas das casas dos Jardins Mangueiral estão em:

resources/plans

Para auxiliar no entendimento e contexto, foram feitas capturas dos mapas dos Jardins Mangueiral, que foram salvas na em:

resources/maps

Banco de dados

O banco principal deve ser tratado como estritamente somente leitura.

Regras obrigatórias

Nunca execute INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, REPLACE, VACUUM, REINDEX, ATTACH ou comandos equivalentes contra o banco original.
Não substitua, mova, compacte, migre ou renomeie o arquivo original.
Não remova arquivos -wal ou -shm sem uma instrução explícita.
Não execute scripts de scraping contra o banco durante uma análise sem autorização.
Use LIMIT em consultas exploratórias.
Não imprima tabelas inteiras no terminal.
Prefira agregações, amostras pequenas e exportações derivadas.
Salve resultados em reports/, exports/ ou data/derived/.
Nunca grave resultados derivados dentro do banco original.
Antes de qualquer análise, confirme o caminho do banco e abra-o em modo somente leitura.

Abertura recomendada em Python

import sqlite3

DB_PATH = "data/imoveis.sqlite"

connection = sqlite3.connect(
    f"file:{DB_PATH}?mode=ro&immutable=1",
    uri=True,
)
connection.execute("PRAGMA query_only = ON")

Se o banco estiver sendo atualizado por outro processo, não use immutable=1; mantenha mode=ro e confirme a consistência do snapshot antes de analisar.

Cliente de linha de comando

sqlite3 -readonly data/imoveis.sqlite

Fluxo inicial obrigatório

Ao iniciar uma nova tarefa de análise:

Identifique o arquivo SQLite correto e seu tamanho.
Leia sqlite_master para listar tabelas, views, índices e triggers.
Examine o esquema real antes de escrever consultas analíticas.
Conte registros por tabela.
Identifique campos de data, preço, área, quartos, localização, URL, anunciante e identificadores.
Verifique valores nulos, duplicidades, formatos inconsistentes e possíveis quebras de coleta.
Descubra se os dados representam:
- anúncios;
- imóveis físicos;
- observações históricas do mesmo anúncio;
- execuções do scraper.
Documente qualquer ambiguidade antes de produzir conclusões.

Não presuma que o modelo lógico descrito em docs/DATA_MODEL.md já existe fisicamente.

Princípios de análise

Diferencie sempre anúncio, imóvel físico e observação histórica.
Um mesmo imóvel pode aparecer em vários anúncios, portais, corretores ou datas.
Um mesmo anúncio pode mudar de preço, descrição, área informada ou status.
Preço anunciado não é preço efetivamente negociado.
Ausência de anúncio não prova venda.
Remoção de anúncio não prova fechamento de negócio.
Campo preenchido pelo anunciante não deve ser considerado confiável sem validação.
Não calcule preço por metro quadrado quando a área não for comparável ou confiável.
Não misture área privativa, útil, construída e total sem separar os conceitos.
Não compare períodos sem verificar mudanças no universo coletado.
Não compare regiões sem controlar tipologia, quartos, área, garagem, estado e padrão do imóvel.
Sempre informe tamanho da amostra, cobertura temporal, filtros e limitações.
Prefira mediana, percentis e intervalos interquartis a médias isoladas.
Mostre a sensibilidade das conclusões a outliers, duplicidades e dados ausentes.

Segurança e desempenho

Nunca exponha credenciais, cookies, tokens, chaves, sessões ou dados pessoais em relatórios.
Não envie o banco ou grandes amostras para serviços externos sem autorização explícita.
Não tente contornar mecanismos de proteção de sites.
Respeite limites de requisição, termos aplicáveis e regras definidas para o scraper.
Evite consultas que façam varreduras desnecessárias repetidas em tabelas grandes.
Use EXPLAIN QUERY PLAN em consultas lentas.
Sugira índices apenas como recomendação; não os crie no banco original.
Para transformações pesadas, crie um banco derivado ou arquivos Parquet/CSV separados.

Código

Escreva scripts reproduzíveis, parametrizados e idempotentes.
Use caminhos relativos ao repositório.
Evite constantes escondidas.
Registre os filtros e premissas usados.
Inclua tratamento de erros.
Use consultas SQL parametrizadas.
Adicione testes para regras de normalização, deduplicação e cálculo.
Não altere arquivos sem relação com a tarefa.
Não faça refatorações amplas sem necessidade.
Não invente significado para colunas pouco claras; documente a dúvida.

Saídas esperadas

Relatórios analíticos devem, sempre que aplicável, conter:

pergunta respondida;
período e universo analisados;
filtros e exclusões;
tamanho da amostra;
método de deduplicação;
qualidade dos dados;
resultados;
limitações;
implicações para a decisão de compra;
consultas ou scripts usados para reproduzir o resultado.

Use gráficos apenas quando eles melhorarem a interpretação. Todo gráfico deve ter título, unidade, período, tamanho da amostra e definição da métrica.

Contexto imobiliário prioritário

As regiões prioritárias são:

Cruzeiro, especialmente Cruzeiro Novo;
Jardins Mangueiral.

Não exclua outras regiões de uma análise exploratória quando forem úteis como referência, mas não desvie o projeto de seu objetivo principal sem instrução.

Para Jardins Mangueiral:

considerar somente casas com planta original de três quartos;
não penalizar automaticamente o fechamento do quintal;
avaliar a funcionalidade real da conversão;
considerar as preferências de QC descritas em docs/PROPERTY_CRITERIA.md;
tratar relatos de moradores como evidência anedótica, não como fato conclusivo.

Atualização do contexto

Não altere estes documentos apenas porque encontrou um padrão no banco.

Atualize-os somente quando:

o usuário corrigir uma premissa;
uma preferência for explicitamente confirmada;
um valor financeiro for atualizado;
uma regra metodológica for aprovada;
o esquema real do projeto for consolidado.

Ao atualizar uma premissa financeira, registre a data de referência e preserve o histórico em Git.

7.0 KiB Raw Blame History