CommunityEscrita e Ediçãogithub.com

jjangjin1999/codex-research-project-skills

Habilidades do Codex para portfólio de pesquisa e fluxos de trabalho iterativos de projetos

O que é codex-research-project-skills?

Esta skill, chamada 'Iterate Research Project', fornece uma estrutura completa para gerenciar projetos de pesquisa de forma iterativa e organizada, utilizando um sistema de diretórios bem definido, um quadro visual (PROJECT_BOARD.html) e práticas de documentação rigorosas. Ela é útil para desenvolvedores e pesquisadores que desejam manter um histórico claro de experimentos, decisões e progresso, permitindo que múltiplas tentativas e ideias sejam gerenciadas sem perda de contexto. A skill suporta plataformas de agentes de IA que podem executar comandos e editar arquivos, como Claude Code, Cursor e Codex, e automatiza a classificação de novas informações, a criação de subprojetos para cada novo experimento e a sincronização de um quadro de resumo a partir de arquivos Markdown. Ela funciona estabelecendo regras claras de onde cada tipo de informação deve ser armazenada (discussões em 1-Docs, experimentos em 0-Project, etc.) e um fluxo de iteração que prioriza a escrita em Markdown antes da atualização do quadro, garantindo que o projeto permaneça 'honesto' e rastreável.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add jiangjin1999/codex-research-project-skills

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Iterate Research Project (Iterar Projeto de Pesquisa)

Use esta skill para manter um projeto de pesquisa honesto à medida que ele muda. O hábito central é: classificar o trabalho, escrever no local mais específico e durável, registrar evidências e, em seguida, sincronizar apenas os resumos e o quadro que os colaboradores precisam.

Duas regras permeiam tudo:

  1. Markdown primeiro, quadro depois. Atualize o markdown de origem ou a anotação _ai primeiro. Só então sincronize PROJECT_BOARD.html.
  2. O quadro é um mapa, não um registro. PROJECT_BOARD.html mostra o estado atual e aponta para evidências. Ele nunca armazena logs brutos, dados privados ou caminhos absolutos.

E um hábito que impulsiona a iteração: nova ideia → novo subprojeto. As tentativas de experimento são o núcleo do trabalho. Quando houver algo para testar, crie um novo 0-Project/<data>_<slug>/ e itere lá, em vez de sobrescrever ou reiterar infinitamente uma única tentativa. Mantenha os subprojetos pequenos e com um único propósito; não tema a duplicação. Isso mantém o histórico anexado apenas (append-only) e comparável (veja references/project-iteration-system.md).

Os subprojetos também têm pistas (lanes):

  • Mainline (Linha Principal) — tentativas atuais que definem o caminho ativo.
  • Parked (Estacionado) — ideias de tentativas futuras capturadas cedo porque o pensamento de pesquisa não é totalmente serial, mas ainda não executadas. Anotação padrão: 0-Project/_parking-lot.md.
  • Archived (Arquivado) — tentativas abandonadas ou substituídas, mantidas com um motivo de parada e evidências. Pasta padrão: 0-Project/_archive/.

Estacione de forma barata. Uma ideia futura pode ser uma entrada curta em _ai/task_plan.md, 1-Docs/ ou 0-Project/_parking-lot.md; crie uma pasta de tentativa completa apenas quando a ideia tiver entradas, critérios ou valor de handoff suficientes.

Roteie discussões e tentativas separadamente: discussão, decisão, comparação e explicação de método vão para 1-Docs/<data>_<topico>.md; tentativas concretas com entradas, critérios, saídas ou resultados vão para 0-Project/<data>_<slug>/; discussão local da tentativa vai para 0-Project/<tentativa>/docs/<data>_<topico>.md.

Autônomo ou dentro de um portfólio. Esta skill é autossuficiente: use-a sozinha para um único projeto em qualquer caminho — nenhum portfólio é necessário. Tudo o que o projeto precisa (pastas, arquivos de entrada, quadro, memória de trabalho, política de git) reside dentro da pasta do projeto. Opcionalmente, quando o projeto está dentro de um portfólio (<slug>-project/<projeto>/), sincronize status, proprietário, prioridade e estado público com o painel do portfólio usando a skill manage-research-portfolio. Quando executar de forma autônoma, pule todas as etapas de "painel de portfólio" e "registro" nesta skill — elas são integrações opcionais, nunca pré-requisitos.

Contrato do Projeto (Project Contract)

Use esta estrutura, a menos que o projeto já tenha nomes equivalentes. Este é o esqueleto copiável _PROJECT_TEMPLATE.

<projeto>/
├── README.md              entrada: objetivo de uma frase, mapa de pastas, início rápido, status atual
├── PROJECT_GUIDELINES.md  regras de sincronização locais do projeto, limites de pastas, classificação HTML
├── PROJECT_BOARD.html     o quadro (看板): mapa do estado atual e navegação
├── GIT_WORKFLOW.md        identidade git + política de commit por alteração para este projeto
├── scripts/
│   └── init_project_git.sh   auxiliar opcional para definir identidade e primeiro commit
├── 0-Project/             tentativas / experimentos concretos (um 0-Project/<data>_<slug>/ por tentativa)
├── 1-Docs/
│   └── README.md          a única entrada de Docs fixa + índice de tópicos
├── 2-Data/
│   └── DATA.md            fonte, proveniência, permissões, versões, esquema, QC, limites
├── 3-Paper_Survey/
│   └── README.md          fila de leitura, anotações de artigos, matriz de evidências, fontes de métodos
├── 4-Skills/
│   └── PROJECT_SKILLS.md  prompts locais do projeto, regras de IA, procedimentos reutilizáveis
└── _ai/
    ├── project_overview.md   objetivo, escopo, status, proprietário, prioridade, próximo
    ├── project_board_spec.md como PROJECT_BOARD.html é gerado/sincronizado a partir das fontes
    ├── task_plan.md          fase atual, plano, bloqueadores, próximo
    ├── findings.md           descobertas estáveis, perguntas em aberto
    └── progress.md           sincronização mais recente e significativa, ações, validação, commit

Os arquivos raiz são entrada + regras + quadro + política git. Tudo o que é concreto vai para a pasta numerada mais correspondente; nunca acumule materiais na raiz do projeto e nunca coloque a visão geral do projeto, regras do quadro ou diretrizes de longo prazo dentro de 0-Project/ (essa pasta é apenas para tentativas concretas).

Classifique Antes de Escrever (Classify Before Writing)

Quando o usuário fornecer novo material, escolha um local de destino e, em seguida, decida se o quadro muda.

Intenção do usuárioLocal de destinoVisualização do quadro que pode tocar
"Isto é uma discussão / método / decisão / comparação"1-Docs/<data>_<topico>.md + atualizar 1-Docs/README.mdMapa de Documentos (Docs Map)
"Isto é um experimento / tentativa concreta"0-Project/<data>_<slug>/; coloque anotações locais da tentativa em sua pasta docs/Tarefas (Tasks)
"Isto é uma anotação sobre uma tentativa existente"0-Project/<tentativa>/docs/<data>_<topico>.mdgeralmente Tarefas, às vezes Mapa de Documentos se alterar o índice do nível do projeto
"Isto é uma ideia de tentativa futura"_ai/task_plan.md, 1-Docs/, ou 0-Project/_parking-lot.md; pasta de tentativa completa apenas se concretogeralmente nenhum, ou uma pista de Tarefas estacionada
"Esta tentativa está abandonada / substituída"mantenha a pasta da tentativa ou mova-a para 0-Project/_archive/; marque como arquivada com motivo de parada, evidências e substituiçãopista de Tarefas arquivada/recolhida
"Isto são informações de dados / benchmark"2-Data/DATA.mdMateriais (Materials)
"Isto é um artigo / fonte externa / evidência"3-Paper_Survey/README.md + matriz de evidênciasReferências (References)
"Isto é um fluxo de trabalho reutilizável / prompt / regra de IA"4-Skills/PROJECT_SKILLS.md(geralmente nenhum)
"Isto altera o status / próxima ação / bloqueador"_ai/project_overview.md, _ai/task_plan.mdVisão geral do topo + Progresso (Progress)

Se a classificação alterar o escopo do projeto, os critérios de avaliação, o limite dos dados, a exposição pública ou se uma tentativa pertence ao projeto, pergunte antes de tratá-la como confirmada. Para nomeação/formatação de baixo risco, escolha a opção conservadora e registre a suposição em _ai/progress.md.

O Quadro (看板) - The Board

PROJECT_BOARD.html é o quadro de projeto único. Ele responde rapidamente: o que é este projeto, o que está atual, o que mudou, onde estão as evidências e por onde continuar. Ele é coordenado com as pastas — cada visualização é alimentada por uma pasta ou arquivo _ai específico.

Elementos básicos:

  • Link inicial / de volta (persistente): um link no início da página, na área superior esquerda da marca. Dentro de um portfólio, faça dele um link Voltar ao painel apontando para a raiz do site /; autônomo, omita-o ou aponte-o para o próprio README.md do projeto. Preserve o que você escolher ao criar, copiar, publicar ou atualizar a página.
  • Status da versão: versão da página YYYY-MM-DD-vN e marcador de última sincronização (opcionalmente um controle de atualização/frescura).
  • Visão geral do topo (sempre visível, leve): nome do projeto, descrição de uma frase, status, proprietário, sincronização recente, foco atual e no máximo uma linha de progresso curta. Fonte: _ai/project_overview.md. Não coloque listas de fase, cartões de versão, listas de tentativas ou rotas de longo prazo aqui.
  • Cinco visualizações mutuamente exclusivas, cada uma mapeada para uma pasta:
VisualizaçãoAlimentada porMostra
Progresso (Progress)_ai/progress.md, _ai/findings.md, 1-Docs/README.mdapenas mudanças principais no nível do projeto: objetivo, escopo, fase, resultado-chave, julgamento, estado público, resumo compacto da versão
Mapa de Documentos (Docs Map)1-Docs/README.md + estrutura raizíndice de tópicos de documentos + uma árvore de estrutura no estilo VS Code Explorer (arquivos/pastas de nível 1 da raiz e nível 2 via <details>/<summary>), apenas nomes seguros para público
Tarefas (Tasks)0-Project/<tentativa>/tentativas da linha principal primeiro; tentativas futuras estacionadas e tentativas arquivadas/obsoletas apenas em pistas recolhidas separadas
Materiais (Materials)2-Data/DATA.mdblocos de dados, publicidade, versão, qualidade, limites de uso
Referências (References)3-Paper_Survey/README.mdartigos, fontes de métodos, status de evidências, impacto; apenas se houver conteúdo

Regras do quadro: não invente proprietários, status, prioridade ou fases futuras; não adicione uma visualização independente de "próximo passo" (a próxima ação reside na visão geral do topo, _ai/task_plan.md ou uma tentativa); use <details> recolhido para tentativas e a árvore de estrutura; mantenha-o como uma bancada de pesquisa silenciosa, não uma página de destino. Ideias futuras e tentativas abandonadas não devem competir visualmente com o caminho ativo. As regras de geração residem em _ai/project_board_spec.md. Veja references/project-board.md para o contrato completo.

Ciclo de Iteração (Iteration Loop)

  1. Restaure o contexto de _ai/project_overview.md, _ai/project_board_spec.md, _ai/task_plan.md, _ai/findings.md, _ai/progress.md e do README da pasta relevante.
  2. Confirme a identidade Git do operador antes de editar os arquivos do projeto; se estiver faltando, peça ao usuário para configurar a sua própria e pause.
  3. Nomeie a iteração atual em uma frase: pergunta, tentativa ou decisão.
  4. Crie ou atualize o arquivo de origem mais específico primeiro.
  5. Registre descobertas que mudam a direção em _ai/findings.md; registre ações, validação e caminhos com falha em _ai/progress.md.
  6. Atualize _ai/task_plan.md quando a fase, bloqueador ou próxima ação mudar.
  7. Antes da compressão de contexto, após concluir uma pequena etapa, ou antes de mudar de tópico/subprojeto, escreva um handoff compacto no arquivo Markdown correspondente mais específico.
  8. Aplique a Escala de Sincronização para decidir se deve tocar em PROJECT_BOARD.html e, em seguida, faça commit dos arquivos seguros alterados com caminhos explícitos.

Compressão de Contexto e Higiene de Handoff (Context Compression And Handoff Hygiene)

Proativamente, escreva o contexto antes que a conversa se torne cara de carregar. Faça isso quando a janela de contexto estiver ficando grande, uma pequena etapa for concluída, um subprojeto atingir um ponto de decisão, ou a próxima ação mudar para outro tópico, projeto ou tentativa.

Escolha o local mais específico:

SituaçãoLocal do handoff
Discussão, decisão ou anotação de método no nível do projeto1-Docs/<data>_<topico>.md
Etapa, observação ou discussão local no nível da tentativa0-Project/<tentativa>/docs/<data>_<topico>.md
Status do projeto, bloqueador, próxima ação ou resumo de validação_ai/progress.md, _ai/findings.md, _ai/task_plan.md
Contexto entre projetos ou do portfólio<slug>-ai/<data>_<topico>.md do portfólio, se existir um portfólio

Campos mínimos do handoff: objetivo atual, etapa concluída, decisões principais, caminhos de evidência, perguntas não resolvidas, próxima ação e se a sincronização do quadro é necessária. Mantenha isso compacto; não cole transcrições completas ou logs brutos.

Escala de Sincronização (Sync Scale)

Julgue cada mudança contra esta escala antes de editar o quadro.

NívelGatilhoAtualização
0Exploração somente leitura, nenhuma nova decisãoNada
1Descoberta menor, pequeno ramo com falha, anotação temporáriaApenas Markdown ou _ai
2Novo artefato/caminho/resultado de QC, bloqueador, próxima ação, status, mapa de documentos, árvore de estrutura, limite de dados, referência ou tentativa alteradaMarkdown de origem ou _ai, depois sincronize PROJECT_BOARD.html
3Fase, marco, declaração pública, proprietário, prioridade ou estado público alteradosMarkdown de origem, quadro, PROJECT_GUIDELINES.md e — apenas se o projeto pertencer a um portfólio — o painel do portfólio

Anotações de handoff de contexto são geralmente Nível 1. Eleve-as para Nível 2 apenas quando alterarem a próxima ação, status, bloqueador, mapa de documentos, limite de dados, estado da referência ou estado da tentativa.

Não sincronize o quadro a cada edição. Sincronize quando um colaborador precisar do novo estado.

Registros de Subprojeto (Subproject Records)

Cada 0-Project/<data>_<slug>/README.md deve responder: qual pergunta a tentativa testa; quais entradas, artigos, anotações de dados ou suposições ela usa; o que foi executado ou raciocinado (objetivo, hipótese, entradas, comando, métricas); o que falhou, mudou ou se tornou estável; a conclusão e a próxima ação; e se afeta o status do projeto, anotações de dados, anotações de literatura ou o quadro. Coloque discussões locais da tentativa, handoffs de etapa e anotações de design na pasta docs/ dessa tentativa.

Registre tentativas com falha. Um caminho com falha com um motivo claro é um ativo útil do projeto. Se estiver abandonado ou substituído, marque-o como arquivado com o motivo da parada, substituição, se houver, última evidência e o que não repetir; mostre-o no quadro apenas como um item recolhido secundário quando atingir uma fase estável ou ponto de decisão.

Dados e Literatura (Data And Literature)

  • Use 2-Data/DATA.md para proveniência, versões, classe de acesso, locais permitidos, esquema, QC e limites de artefatos derivados. Mantenha dados derivados do projeto (features, trajetórias, tabelas prontas para análise, intermediários de QC) sob 2-Data/ deste projeto, não na área de dados global. Nunca escreva registros confidenciais brutos, exemplos com identificação, credenciais ou trechos não publicados em anotações, no quadro ou em cópias públicas.
  • Use 3-Paper_Survey/README.md para evidências que podem mudar métodos, avaliação, escopo ou interpretação. Resuma artigos por problema, método, dados ou benchmark, resultado, limitação e implicação para este projeto. Use uma matriz de evidências quando várias fontes se referirem a uma única afirmação. Prefira paráfrase concisa e links em vez de citações longas.

Referências (References)

  • Leia references/project-iteration-system.md ao criar estrutura de projeto, arquivos de entrada, subprojetos, arquivos de memória de trabalho ou regras de sincronização.
  • Leia references/project-board.md ao criar, revisar ou sincronizar PROJECT_BOARD.html.
  • Leia references/data-and-literature.md antes de lidar com anotações de dados, proveniência de benchmark, resumos de literatura ou atualizações de evidência para decisão.

Habilidades Relacionadas