cd-browser/instructions-agent.md

Agent Instructions: Universal Python Project Template

Project Overview

This repository is a universal and adaptable Python template intended to serve as a professional starting point for new projects.

Core Directives

1. All code, comments, variables, string literals, commit messages, and documentation must be written in English.
2. Use Python 3.11+ with type hints whenever possible.
3. Follow clean code principles and PEP 8.
4. Keep modules small, cohesive, and maintainable.
5. Use consistent docstrings for public classes and functions.
6. Prefer explicit error handling over silent failures.

Architecture Guidelines

1. Keep business logic separate from infrastructure concerns.
2. Avoid mixing configuration, I/O, and domain logic in the same module.
3. Prefer reusable services over duplicated logic.
4. Do not introduce unnecessary complexity or premature abstractions.

Quality Standards

1. Every meaningful feature should include tests.
2. Run formatting, linting, and type checks before considering a task complete.
3. Keep the README updated whenever setup, commands, or structure changes.
4. Do not leave placeholder code unless clearly marked.

Tooling

• Testing: pytest
• Formatting: black
• Linting: ruff
• Static typing: mypy

Expected Project Structure

src/app/ tests/ scripts/ README.md instructions-agent.md pyproject.toml

Agent Workflow

1. First understand the repository structure.
2. Propose a short implementation plan before major changes.
3. Reuse existing modules whenever possible.
4. Keep changes minimal, coherent, and production-oriented.
5. Validate changes with tests and quality tools when possible.

Application Specification

This repository includes an application specification that defines the expected behavior of the project.

Primary specification file:

• specs/cd_browser_spec.md

Agent rules:

1. Before implementing any feature, read the application specification.
2. If implementation details are unclear, follow the specification first.
3. If the specification conflicts with a previous assumption, the specification takes precedence.
4. Keep implementation aligned with the MVP scope unless explicitly asked to extend it.
5. After code changes, run the appropriate validation workflow defined by this repository.

AI Worklog Policy

This repository maintains an AI-assisted development log.

Files:

• docs/ai-worklog.md
• docs/ai-prompts.md

Rules:

1. After every significant plan or build task, append a concise worklog entry to docs/ai-worklog.md.
2. Each worklog entry must include:
   • date
   • task type (plan or build)
   • short objective
   • files inspected or modified
   • key decisions
   • validation commands run
   • result
   • unresolved issues if any
3. When a prompt meaningfully changes architecture, behavior, workflow, debugging direction, or project structure, append the prompt (or a concise cleaned version of it) to docs/ai-prompts.md.
4. Do not store private chain-of-thought or internal reasoning.
5. Store only concise, user-facing summaries of what was done.
6. Keep entries chronological and easy to scan.

Mandatory AI Logging

Every significant AI interaction in this repository must be logged.

This applies to:

• plan tasks
• build tasks
• debugging tasks
• documentation tasks
• architectural discussions that affect the project

Required files:

• docs/ai-worklog.md
• docs/ai-prompts.md

Mandatory rules:

1. After every significant plan task, append a concise entry to docs/ai-worklog.md.
2. After every significant build task, append a concise entry to docs/ai-worklog.md.
3. If the task was driven by a meaningful prompt, also append an entry to docs/ai-prompts.md.
4. Logging is part of the task itself and must not be skipped.
5. The task is not complete until the logs are updated.

Each worklog entry must include:

• date
• task type (plan or build)
• short objective
• files inspected or modified
• key decisions
• validation commands run, if any
• result
• unresolved issues, if any

Each prompt log entry must include:

• date
• task type (plan or build)
• short prompt summary
• scope
• result summary

Rules:

• Do not store chain-of-thought or private reasoning.
• Store only concise user-facing summaries.
• Keep entries chronological.
• Even small but meaningful tasks must be logged.