Saky
801544951f
- add AI worklog and prompt logs - enforce logging rules in instructions-agent.md - require AI agents to record plan and build tasks - establish traceable AI-assisted development workflow
131 lines
4.3 KiB
Markdown
131 lines
4.3 KiB
Markdown
# 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.
|