Saky
65508d263f
- add dedicated history mode UI (toggle with `h`) - allow navigation inside history with arrows - allow selecting history entries with Enter - add tests for history mode behavior - introduce AI development logs (`ai-worklog.md`, `ai-prompts.md`) - add AI worklog policy to `instructions-agent.md`
86 lines
3.1 KiB
Markdown
86 lines
3.1 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.
|